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PREFACE 


Document Objectives 
This manual describes some of the tools that make up the Professional 
Developer's Tool Kit. For some tools, this manual provides the only 


source of information. For others, this manual supplements) other 
manuals. Tools not included in this manual are documented in their 


Own manuals. 
Intended Audience 
This document is intended for programmers who are familiar with the 


Tool Kit development cycle and at least one of the Tool Kit languages. 
It 1S recommended that you read the Tool Kit User's Guide before using 


this manual. 

Document Structure 

This manual describes 11 tools, one per chapter: 
1. Application Diskette Builder (ADB) 

2. Communications Services 

3. Fast Install 

4. File Control Services (FCS) 

5. Frame Development Tool (FDT) 

6. Installation Command Language 

7. MACRO-11 Assembler (PMA) 

8. POSRES User Interface Library Routines 
9. Print Services 

10. PROSE Text Editor 

11. PRO/SORT 


The error message lists for ADB and FDT are extraordinarily large, 
thus Appendices A and B are devoted to those lists. 


Appendices C and D provide tabular information related to POSRES user 
interface programming and are duplicated in the Tool Kit User's Guide. 


Appendix E lists the error codes returned by the Professional 
Operating System (P/OS). 
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PREFACE 


Associated Professional 300 Series Documentation 


This manual is part of the Tool Kit documentation set. Related 
documentation is referenced throughout the book. For abstracts and 
order numbers of other Tool Kit documents, see the Tool Kit User's 
Guide. 


Syntax Conventions 


In this manual, syntax diagrams are presented in a format intended to 
make them easy to read and understand. Most languages do not require 
that you format your code in any particular way; therefore, you should 
not regard tne formats used in this manual as mandatory. 


Because some languages include the symbols normally used as 
conventions in syntax diagrams, the following conventions are used: 


Convention Meaning 

BOLD UPPERCASE Bold uppercase letters indicate elements that you 
must use exactly as shown. 

UPPERCASE LETTERS Uppercase letters indicate elements that you’ can 
omit or use exactly as shown. 

bold lowercase Bold lowercase letters indicate elements that you 
must replace according to the description in the 
text. 

lowercase letters Lowercase letters indicate elements that you’ can 


omit or replace according to the description in 
the text. 


Shaded areas containing bold letters indicate a 
list of elements from which you must select one. 


Shaded areas containing non-bold letters indicate 
a list of elements from which you can optionally 
select one. 


element,... A comma followed by a horizontal ellipsis 
indicates that you can repeat the preceding 
element one or more times, separating the 


elements with commas. 


A vertical ellipsis in a figure or example means 
® that part has been omitted for brevity. 
red letters Red letters distinguish what you type from what 


the computer types. 


CHAPTER 1 


APPLICATION DISKETTE BUILDER (ADB) 


The Application Diskette Builder (ADB) is a Professional 350 
application that creates a master copy of an application that can be 
reproduced for distribution. The diskette is the distribution medium 
for Professional software. ADB uses the information in your 
application command (.INS) file to copy your application from the hard 


disk to one or more diskettes, from which it can be installed on other 
systems. . 


A P/OS Hard Disk application can span several diskettes. A P/OS 
Diskette application must be contained entirely on one diskette. 
Multiple applications may be copied to a single diskette if space 
allows. For example, you may be able to distribute the Hard Disk and 
Diskette versions of your application on a single diskette. 


1.1 USING THE ADB 


To prepare a master distribution diskette for your application, follow 
these steps: 


1. If you have not already done so, transfer all application files 
(task images, frame files, installation command file, and so 
forth) to a single directory on your Professional. 


2. If you have not already done so, install the ADB. The Tool Kit 
includes a diskette labelled "Application Diskette Builder." Use 
P/OS Disk/diskette Services to install it. 


3. To invoke the ADB, select it from the P/OS menu on which it was 
installed. The ADB dialogue is described in Section 1.2. 


NOTE 


During the dialogue, you can press MAIN SCREEN to 
return to the P/OS Main Menu. 
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THE ADB DIALOGUE 


ADB displays an introductory frame. Press DO to continue. 
Choose the target system(s). 


ADB displays the menu for choosing the target system for your 
application. Choose P/OS Hard Disk, P/OS Diskette, or both. 


Specify the .INS file(s). 


ADB displays a list of installation files in the current 
directory. Select an installation file for each target system 
selected. (If you selected both target systems, ADB will prompt 
for two installation files.) The installation file can reside in 
any hard disk directory. Press the ADDTNL OPTIONS key if you want 
CO: 


@ Select a file from a different directory 

@® Select a file from a different volume and directory 
@ View the next group of files 

@® Specify the file with an extended file name 


If ADB does not find an .INS file in the current directory, it 
displays the Additional Options menu. 


When you have selected a file, ADB checks it for errors. Refer to 
Appendix A and press RESUME to try again. 


Ready the target diskette. 


If ADB finds no errors, it displays the Diskette Drive Selection 
and Initialization menu. 


e If the diskette contains information that must be preserved, 
select one of the options that indicates copying will take 
place without initializing the diskette. Existing information 
will be saved. 


NOTE 


If the .INS file contains a MOUNT line _ for 
this diskette, ADB will expect the diskette to 
have the same volume name as that specified in 
the MOUNT line. 


THE ADB DIALOGUE 


@® If you do not want to preserve any existing information on the 
target diskette, select an option that will initialize the 
diskette. When ADB prompts for the volume name, enter’ the 


desired volume name. ADB will check the volume for bad 
blocks. 


NOTE 


If your .INS file references this diskette in a 
MOUNT line, you will not be prompted for a volume 
name. 


Create the checkpoint file, if needed. 


ADB prompts for the number of blocks to be allocated for a 
checkpoint file. 


NOTE 


A checkpoint file is needed for applications’ that 
run on P/OS Diskette systems. If your application 
will run on P/OS Hard Disk only, specify zero. 


If your application, along with its resident libraries, callable 
system tasks, device drivers and graphics support will fit in the 
default checkpoint space of 200 blocks (100kb), simply press DO. 
If your application requires more than 200 blocks of memory, 
create a checkpoint file. 


To calculate the maximum number of blocks, multiply the number of 
blocks that the largest task requires by the number of tasks in 
the application. This calculation will always give you’ enough 
checkpoint space. Allocate this many blocks if there is 
sufficient room on the diskette. For example, if the application 
consists of two tasks, one requiring a maximum of 48kb and one 
requiring a maximum of 20kb, you would allocate 192 blocks for the 
checkpoint file. 


To determine the minimum number of blocks’ required for. the 
checkpoint file, add the maximum size of all tasks’ in the 
application in kilobytes, and multiply by two. Do not count 
libraries, only tasks. For example, for the same application, 
with tasks requiring 48kb and 20kb, you would allocate 136 blocks 
for the checkpoint file. 
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NOTE 


This second calculation determines the minimum 
number of blocks. More may be needed. If you use 
this calculation and your application fails during 
testing, restart the ADB and allocate more blocks 
at this stage. 


Copy the .INS file to the first diskette. 


@e If you are building for a P/OS Diskette application, ADB now 
automatically copies the installation file to directory 
[ZZAPPL] as DISKETTE.INS. 


@e If you are building a P/OS Hard Disk application, ADB will ask 
for the name of the application directory to be created on the 
target diskette. You can specify any name; the .INS file will 
be copied to an .INS file with the same name. 


@® If you are building for both hard disk and diskette systems, 
and you intend to use the same application directory for both, 
specify the name [ZZAPPL] for the new directory of the hard 
disk - INS file. ADB will name the installation file 
ZZAPPL.INS. You can place the application files for P/OS 
Diskette and P/OS Hard Disk in separate directories if 


diskette space permits. Use separate directories only if 
different application tasks or files are to be used on the two 
systems. 


If an .INS file contains errors, ADB will not copy the file and 
will display an error message. Check the format of the .INS file, 
correct the file, and start again. 


Copy the files to the target diskette(s). 


The ADB now copies the files listed in the FILE lines of the  .INS 
file to the target diskette. If ADB encounters a MOUNT line (P/OS 
Hard Disk only), it will prompt you to insert a new diskette and 
will repeat the initialization process in step 3. ADB then 
resumes copying files with the next FILE line, and continues until 
all MOUNT and FILE lines have been accounted for. 


ADB will check for a directory specification for each filename. 
If the filename includes a directory specification, ADB will look 
in that directory for the file to be copied. If the filename does 
not include a directory specification, ADB will look in the 
directory that contains the .INS file. In either case, if ADB 
cannot find the file, it will display a menu listing all hard disk 
directories. Select the directory in which the file resides. 
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If the filename includes a directory specification, ADB copies 
that file to that directory, creating a directory automatically if 
none of that name already exists on the target diskette. If the 
filename does not include a directory specification, ADB copies 
that file to the directory to which it copied the .INS file. Lt 
for any reason the ADB cannot copy a file, ADB displays an error 
message, then redisplays the first ADB- screen. The files 
previously copied will, of course, still be on diskette. You may 
want to delete them to reclaim that space. 


You will see a confirmation message when all files have been 
copied. 
Label the completed diskette(s). 
You should label your application diskettes with: 
@® The application's name 


@ The volume name (This must match the name provided in the 
corresponding MOUNT line, if any.) 


e@ A brief description of the application's purpose 

@ The number of diskettes on which the application resides 

@® Minimum hardware configuration required 

e Hardware options required 

@ Media space required 

If your application spans more than one diskette, you should also 


indicate which is the first diskette, that is, which diskette 
contains the application's .INS file. 


CHAPTER 2 


COMMUNICATIONS SERVICES 


Communications Services allow you to perform communications operations 
on the Professional. Your application program can access the services 
either by calling communications routines, or by spawning tasks that 
execute communications utility programs. For example, your program 
can call a routine named CCATT to attach a phone line, or it can spawn 
a task that executes a terminal emulation utility. 


The communications services fall into three categories: 


1. Base System Services, which DIGITAL provides with the P/OS 
operating system. These services include an asynchronous driver 
(XKDRV) for the Communication Port as well as a communications 
service library (COMLIB). 


2. PRO/Communications Services, which DIGITAL supplies as an optional 
application, providing features beyond those supplied with the 
base system. These services include utility programs (Such as a 
terminal emulator), as well as additional communications routines. 


3. Telephone Management System (TMS) Services, which DIGITAL supplies 
aS another optional application. The TMS services consist of a 
set of routines that allow your application to control the TMS 
hardware. Note that this hardware must be installed on the 
Professional in order to call the TMS routines. 


The next section presents general information common to all the 
communications services. Succeeding sections describe each of the 
three kinds of services. 


2.1 OVERVIEW OF COMMUNICATIONS SERVICES 


Before executing any communications service that performs I/0, you 
must assign a logical unit number (LUN) to the required communication 
line(s). The device names for the communication lines are: 


OVERVIEW OF COMMUNICATIONS SERVICES 


Device Name Represents 

XKO: Communication Port 
XT1l: TMS Line l 

XT2: TMS Line 2 

XT3: TMS Voice Unit 


You can assign a LUN to a communication line either as ae static 
assignment at task build time, or by using the ALUNS system directive 
(described in the P/OS System Reference Manual). The system 
automatically incorporates the communications impure data area in the 
root of any task linking to the COMLIB cluster library. 


If you want to service unsolicited events on the communication line, 
you can call the CCATA routine to attach the line. You are notified 
of all unsolicited events via the user asynchronous system trap (AST) 
routine declared in the call. 


You can perform either synchronous or asynchronous I/O to the 


communication line driver. The event flag number (EFN) -- a parameter 
On your call line -- indicates the type of I/O performed. For 


asynchronous I/O, the system sets the event flag on completion of the 
I/O transfer. 


Parameters in calls to the communications routines are all 
single-length integers, unless the description of a particular 
parameter specifies otherwise. For details on a routine's parameters, 
refer to the routine's description later in this chapter. 


For a description of the calling conventions for all the routines, 
refer to the Tool Kit User's Guide. 


2.1.1 Status Returns 


All communications routines check for proper EO termination, 
returning a double-length status value in the first parameter in the 
call line. The first word of the status value contains a_ code 
indicating whether or not the I/O termination was successful. The 
second status word contains a code indicating the specific error, if 
an error occurred. The routine obtains this code from the first word 
of the I/O status block (IOSB). You can check the first byte of this 
word to determine the specific error. 


For routines that accept calls issuing an asynchronous QIO, your 
application must specify an additional double-length area for the 
IOSB. If you use the routine in its synchronous mode, the routine 
Signals its termination status as described above. However, if you 
use the routine's asynchronous mode, the first status word indicates 
only whether or not the routine has successfully issued the QIO. Your 
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program must test the IOSB to determine if the I/O terminated 
successfully after the QIO has completed. For some routines, the 
system signals QIO completion by setting an event flag that you 
specify in the call line. 


COMLIB defines all returned status codes as global symbolic constants. 
For those languages that allow you to define external constants, the 


Professional Application Builder (PAB) resolves the values at build 
time. 


Each status return has a symbolic name, called the return code. Table 
2-1 shows the return codes and their values. Success returns are 
positive values; error returns are negative values. 


For the possible return codes for a particular routine, see that 
routine'’s description later in this chapter. 
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Table 2-l: Communications Status Return Codes 


Return Code Value Meaning 
CS~.SUC 1 Successful reply 
CS.NTB 2 Successful, no translate table 
(CCLCRG routine only) 
CS.FUN 2 Successful, function key exit 
Second word contains the key value 
CE.UNO -l Unsupported message option 
CE.MFE —2 Message format error 
CE.REJ ~3 Invalid message option 
Second word contains: 
CZsDIS a Operation disallowed 
C2.UAB 2 User requested abort 
C2.FTB 3 File exceeds maximum 
C2.IAC 4 Invalid action code 
C25: BSY 5 File transfer Subsytem busy 
C2.BPL 6 Bad parameter 
C2é1DL 7 No operation currently active 
C2.IPW Sis Invalid password 
C2.SAA 9. Server already active 
C2.NAE 64. File Transfer Subsytem not attache 
CE.MSC —4 Message type out of sync 
CE.DDC = Data Link Error 
CE.IEA -6 Internal error abort 
CE.RMS -7 PRO/RMS error 
Second word contains the PRO/RMS 
error code 
CE.LIB -9, Library mismatch error 
CE.STU —-ll. File transfer startup in 
progress. 
CE.PRM -16. External parameter error 
CE.DIR -l7. RSX Directive error 
Second word contains the DSW 
CE.IER -18. I/O termination error 
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CE .NNF ~19. Name not found in phone book 


CE.CTB -20. CTAB error in msg, menu etc. 


2.1.2 Line Descriptor Block 


The line descriptor block (LDB) stores line characteristics, which 
describe how voice or data travels over your communication line. You 
need this information to set up the line, either for a voice or data 
connection. You can transmit via the Communication Port or Telephone 
Management System (TMS) telephone lines. (We describe TMS later in 
this chapter.) 


Each line characteristic consists of one byte, stored in the LDB in a 
position-dependent manner. That is, each value's position in the LDB 
indicates what characteristic it represents. The characteristic 
positions are as follows: 


Byte 0 : Transmit Rate (Bits per sec) 


Byte 1 : Receiver Rate (Bits per sec) 
Byte 2 : Number of Data Bits 

Byte 3 : Number of Stop Bits 

Byte 4 : Parity Checking and Generation 
Byte 5 : Odd or Even parity 

Byte 6 : XON/XOFF Recognition 


Byte 7 : Software 7-bit characters 

Byte 8 : Auto answer ring count 

Byte 9 : Modem Type 

Byte 10 : Dial Mode 

Byte ll : Data Mode 

Byte 12 : DTMF Tone Time (10 ms multiples) 

Byte 13 : DTMF Interdigit Time (10 ms multiples) 
Byte 14 : TMS Silence Detect Timeout 


Byte 15 : Reserved 
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To change a line characteristic, first call CCGMC or CCLCRG to get 
either the current settings or the default settings. Then modify the 
particular characteristic byte or bytes and write the new set back 
using CCLCRP or CCSMC. Note that CCLRP does not check for validity 
when you write back the default characteristics. 


In general, all the settings in the LDB must be valid for the line to 
which you write them. | 


Much of the information contained in the line descriptor block is 
optional and depends on the type of link that you are setting up. For 
a voice link, the system uses only those fields that control the 
manner in which the call is dialed. Note that some data options 
available via TMS are unavailable on the Communication Port, and vice 
versa. When you choose such an option, it is ignored, except where a 
functional incompatibility occurs (for example, you can specify the 
200 baud rate only for TMS lines). 


Note that a particular line characteristic (a byte in the LDB) 
corresponds to the second byte in the QIO functions SF.GMC and SF.SMC. 
(The communications routines that handle the line characteristics use 
these two OQIO functions. See the P/OS System Reference Manual for 
details.) 


2.1.3 Autodial Modem Support 


The XKO: device handles any autodial modem that accepts a dial 
sequence as data passed on the primary transmit lead. This type of 
modem ususally has both a start control sequence (indicating that a 
telephone number follows) and an end sequence (indicating the end of 
the telephone number). Not all modems require the end sequence. 


You can use two methods of dialing through the Communication Port when 
an autodial modem is attached. The first method is to define the line 
as hardwired and transmit the dial sequence as data to the modem. 
Most autodial modems give some kind of response indicating whether or 
not the connection was successfully established. This can be read as 
data received from the modem. Note that this method will only work on 
XKO: (one side effect is that a hardwired line automatically answers 
any call because the DTR signal is held high). 


The second method supports XKO:, XTl: and XT2: lines. A program 
that uses this method need not know the specific line type that the 
call is dialed on. To set up the system to support an autodial modem 
on XKO: you must define a translate table as the XKO: device. 


The translate table contains three parts: 
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@® The first part defines a set of character translations. 
® The second part defines the start sequence for the autodial modem. 


@® The third part defines the end sequence. 


The first part of the translate table defines a set of character 
translations that can occur during the dial operation. This allows 
you to substitute graphics characters for control characters in the 
phone number; also, it allows you to remove format characters from the 
phone number. (The normal format characters for a phone number are 
"cen, men), "-" and " ". An example is [12] (345) 678-9012.) 


You can set the translate table either by calling the Base System 
routine CCMTT (see "Base System Services" later in this chapter), or 
executing the PRO/Communications Setup VEL ty (see 
"PRO/Communications Services" later in this chapter). 


By default (that is, if you do not override the default translate 
table), the XKO: device assumes that a DIGITAL DFO3 autodial modem is 
attached. 


Note that any of the parts of the table can be empty. Look in the 
user handbook for the start and end sequence of the particular 
autodial modem you are using. The translate table as stored _ and 
returned by the CCLCRP and CCLCRG routines begins at the first 
count-byte. 


2.2 BASE SYSTEM SERVICES 


The Base System Services include an asynchronous driver (XKDRV) for 
the Communication Port, as well as a communication service library 
(COMLIB). To perform communications operations, you can either issue 
OQIO requests directly to the XKDRV (see the P/OS System Reference 
Manual), or call the routines in COMLIB. 


If you are writing your program in a high level language, it is best 
to use the COMLIB routines. 


The Base System Services allow you to set up and control ae_etelephone 
connection for data communication. Additionally, the Base Services 
allow you to handle voice communication if you install the optional 
Telephone Management System (TMS). 


The following sections describe the Base System startup and the Base 
System routines. 
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2.2.1 Base System Startup 
When you power up a Professional and boot P/OS, a Base System startup 
program executes. This program loads the asynchronous driver, XKDRV, 


and sets up the default line characteristics. The program is’ present 
on all systems. 


2.2.2 Base System Routines 


This section describes the communications routines that DIGITAL 
provides with the P/OS operating system. 


2.2.2.1 Attach Line (CCATT and CCATA) - There are two attach 
routines. The CCATA routine attaches a line and declares an AST 
routine that your application uses for unsolicited events. The CCATT 
only attaches the line. The caller specifies the AST routine that 
CCATA uses. 
Format: 

CCATT (status, lun) 

CCATA (status, lun, ast, param) 
status A two-word status block as described in Section 2.1.1. 
lun The logical unit number for the communication line. 


ast The entry point for an unsolicited event AST. 


param A number that identifies this line as the input source upon 
entry to an unsolicited event AST routine. 


Status: 
CS.SUS Successful 
CE.PRM Service call parameter error 
CE.DIR RSX Directive error 
Second status word contains the DSW 
CE.IER I/O Termination error 
Second status word contains the IOSB first word 
CE.IEA Internal error 
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Notes: 


The routines CCATT and CCATA issue asynchronous QIOs to perform the 
attach, which always completes immediately. However, if another task 
has attached the line prior to your request, you receive the status 
return code CE.IEA, with the second status word equal to zero. The 
zero indicates that the attach request will pend until the line is 
free. When the line is free, the driver updates the status parameters 
with the completion status of the attach QIO (that is, the driver 
asynchronously writes the IOSB to the status block). 


To avoid data corruption upon completion of the attach, you might want 
to use a separate status block when calling CCATT or CCATA. 


2.2.2.2 Detach Line (CCDET) - This routine detaches a line previously 
attached by the CCATT or CCATA routines. 


Format: 
CCDET (status, lun) 


status A two-word status block as described in Section 2.1.l. 


lun The logical unit number for the communication line. 
Status: 

CS.SUC Successful 

CE.PRM Service call parameter error 

CE.DIR RSX Directive error 


Second status word contains the DSW 


CE.IER I/O Termination error 
Second status word contains the IOSB first word 


CE.IEA Internal error 
2.2.2.3 Set Line Characteristics (CCSMC) - This routine modifies line 
characteristics to the required settings. The routine writes the 


characteristics stored in the ldb parameter (see the call line) to the 
appropriate driver. 
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Format: 

CCSMC (status, lun, ldb) 
status A two-word status block as described in Section 2.1.1. 
lun The logical unit number for the communication line. 


ldb The line descriptor block containing the new line 
characteristics. The block size must be 16 bytes. 


Status: 
CS.SUC Successful 
CE.PRM Service call parameter error 
CE.DIR RSX Directive error 
Second status word contains the DSW 
CE.IER I/O Termination error 
Second status word contains the IOSB first word 
CE.IEA Internal error 


2.2.2.4 Get Line Characteristics (CCGMC) - This routine returns’ the 
current line characteristics for the specified line. 


Format: 

CCGMC (status, lun, ldb) 
status A two-word status block as described in Section 2.1.1. 
lun The logical unit number for the communication line. 


ldb A buffer into which the line characteristics may be returned 
in ldb format. The buffer size must be 16 bytes. 


Status: 
CS.SUC Successful 
CE.PRM Service call parameter error 
CE.DIR RSX Directive error 
Second status word contains the DSW 
CE.IER I/O Termination error 
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Second status word contains the IOSB first word 


CE.IEA Internal error 


2.2.2.5 Get/Put Line Configuration Record (CCLCRG and CCLCRP) - You 
can use these routines to retrieve and modify the line configuration 
record for the specified line. 
Format : 

CCLCRG (status, dev, unit, ldb, ttble) 

CCLCRP (status, dev, unit, ldb, ttble) 


status A two-word status block as described in Section 2.1.l. 


dev A two-byte ASCII string containing the device mnemonic. 
unit The unit number in binary. 
ldb The line descriptor block. The block size must be 16 bytes. 


ttble A 64-byte translate table for converting internal telephone 
numbers to a format accepted by an autodial modem. The table 
begins at the first count-byte. 


Status: 
CS.SUC Successful 
CS.NTB Successful, no translate table defined 
CE.PRM Service call parameter error 
CE.DIR RSX Directive error 
Second status word contains the DSW 
CE.RMS File I/O error 
PRO/RMS-11 error code passed in second word 
CE.IEA Internal error 
Notes: 


These routines perform file I/O to the communications setup data file. 
(This file stores default line characteristics, translate tables, and 
other information used by the communications services.) In order to 
perform the file I/0, you must assign a logical unit number to the 
setup data file. Insert the following global definition command in 
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your PAB command (.CMD) file: 
GBLDEF = CMSLUN:1lun 


where "lun" is the logical unit number that the system associates with 
the communications setup file. 


See the section on command files in this manual for further 
information. Also, see the description Of GBLDEF in the 
RSX-11M/M-PLUS Task Builder Manual. 

If you specify "ttble" without having previously defined a translate 
table, CCLCRG assigns the value zero to the first three bytes of the 
translate table buffer. No status return indicates this condition. 


You can set up a translate table either by calling CCLCRP or by uSing 
the PRO/Communications application to "Set modem characteristics." 


2.2.2.6 Set Translate Table (CCMTT) - This routine allows you to set 
a translate table when you are using an autodial modem. 


Format s 
CCMTT (status, lun, ttble) 
status A two-word status block as described in Section 2.1.1. 
lun The logical unit number for the communication line. 
ttble A 64-byte translate table for converting internal telephone 


numbers to a format accepted by an autodial modem. The table 
begins at the first count-byte. 


Status: 
CS.SUC Successful 
CE.PRM Service call parameter error 
CE.DIR RSX Directive error 
Second status word contains the DSW 
CE.IER I/O Termination error 
Second status word contains the IOSB first word 
CE.IEA Internal error 
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2.2.2.7 Dial Call (CCDIAL) - This routine dials a call in data mode 
on a designated communication line. The type of call you establish 
(voice or data) depends on the current ‘data mode’ of the device. Use 
the CCSMC routine to set the data mode. 


Format: 


CCDIAL (status, lun, tel, len, efn, iosb, tmo) 


Status A two-word status block as described in Section 2.1.l. 


lun The logical unit number for the communication line. 

tel A string up to 32 bytes long representing a telephone number. 
len The length of the telephone number. 

efn An event flag the system sets on completion of the operation, 


or zero if you perform the operation synchronously. 
iosb A double-length array used as an IOSB. 


tmo The time out period for the dial to complete. Specify the 
value as follows: 


bits 0-7 Number of ten-second intervals, up to 255 decimal 
bits 8-15 Number of one-second intervals, up to 255 decimal 
The longest possible time out interval that you can specify is 
255 decimal seconds. If the time out value is larger than 255 


decimal seconds, the routine uses 255 seconds. 


If you do not specify tmo, the QIO terminates immediately. 


Status: 
CS.SUC Successful 
CE.PRM Service call parameter error 
CE.DIR RSX Directive error 
Second status word contains the DSW 
CE.IER I/O Termination error 
Second status word contains the IOSB first word 
CE.IEA Internal error 
Notes: 
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Before issuing the dial, the driver raises DTR and RTS. These may be 
dropped depending upon the termination status of the dial, as 
described in the following paragraphs. 


If you specify a zero time out (or no time out parameter), the driver 
waits 60 seconds to establish carrier. If, at the end of this period 
carrier is not raised, then DTR and RTS are dropped. 


If you specify a non-zero time out, the request completes after the 
time out period or after a connection is established. If the time out 
period expires, then the driver drops DTR and RTS and the routine 
returns an IE.DNR error in the first word of the I/O status block. If 
the modem raises carrier before the time out period expires, the 
routine returns IS.SUC in the first word of the I/O status block. 


When dialing a call, the driver automatically deletes the format 
effectors. These include left and right parentheses, the dash, and 
the space character. The driver also inserts the appropriate start 
and end codes for a DFO3 modem, provided that you use the default 
translate table. For other types of format effector editing, or _ for 
support of autodial modems with different start/end codes, you must 
set up a new translate table (see the description of the CCMTT routine 
earlier in this chapter). 


2.2.-2-8 Answer Call (CCANS) - This routine answers a call on the 
specified telephone line in data mode. The routine answers the call 
in the current mode of the line (voice or data). 

Formats: 


CCANS (status, lun) 


status A two-word status block as described in Section 2.1.l. 


lun The logical unit number for the communication line. 
Status: 

CS.SUC Successful 

CE.PRM Service call parameter error 

CE.DIR RSX Directive error 


Second status word contains the DSW 


CE.IER I/O Termination error 
Second status word contains the IOSB first word 


CE.IEA Internal error 
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Notes: 


If no connections occurs within 60 seconds, the routine returns” an 
error status. You should call this routine in response to a "ring 
indicator" unsolicited event. 


In the case of a TMS line where the call has already been established 
in voice mode, this routine causes the TMS software to connect the 
designated modem in ‘answer’ mode when a change mode command is issued 
to place the line in ASYNC mode. The corresponding party must have 
placed their modem in ‘originate’ mode. (Use the CCORG routine, 


followed by a change mode to ASYNC, to place a modem in originate 
mode.) 


The converse of this is also true. That is, to change a line from 
ASYNC mode to voice mode, use the following procedure: 


1. Use CCPTGV to indicate that the line is not to be disconnected 
when carrier loss occurs. 


2. Use CCMODE to set the desired mode, which does not take effect 
until you issue a CCANS or CCORG call. 


3. Use CCANS or CCORG to effect the mode change. 


2.2.2.9 Originate Call (CCORG) - This routine initiates the 
connection in originate mode, once the line has already been 
connected. You can use the routine to determine whether or not a 
connection currently exists, or to raise DTR and RTS before making a 
Manual connection. 
Format: 

CCORG (status, lun, efn, iosb, tmo) 
status A two-word status block as described in Section 2.1.1. 


lun The logical unit number for the communication line. 


efn An event flag the system sets on completion of the operation, 
or zero if you perform the operation synchronously. 


iosb A double-length array to be used as an IOSB. 


tmo The optional time out parameter. See the description of the 
tmo parameter in the description of CCDIAL. 


Status: 
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CS.SUC Successful 
CE.PRM Service call parameter error 
CE«DIR RSX Directive error 


Second status word contains the DSW 


CE.IER I/O Termination error 
Second status word contains the IOSB first word 


CE.IEA Internal error 
Notes: 


If you you do not specify a time out parameter, the driver raises DTR 
and RTS. You can then initiate a manual connection in the normal 
manner. If you have specified that the line has a modem, DTR is not 
raised until you issue CCORG with no time out parameter. When using 
CCDIAL, the driver automatically raises DTR before dialing a call. 


If you specify a zero time out parameter, the request completes 
immediately. When carrier is down, the driver drops DTR and RTS and 
the routine returns an IE.DNR error in the first word of the IOSB. 
When carrier is up, the routine returns IS.SUC in the first word of 
the IOSB. 


If you specify a non-zero value in time out, the request completes 
either after the time out period or after a connection is established. 
If the time out period expires, the driver drops DTR and RTS and the 
routine returns an IE.DNR error in the first word of the IOSB. If 
carrier is up (or comes up before the time out period expires), the 
routine returns IS.SUC in the first word of the IOSB. 


2.2.2.10 Hangup a Call (CCHNG) - This routine disconnects a call 
previously established on a specified line. 


Format: 
CCHNG (status, lun) 


status A two-word status block as described in Section 2.1.1. 


lun The logical unit number for the communication line. 
Status: 

CS.SUC Successful 

CE.PRM Service call parameter error 
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CE.DIR RSX Directive error 
Second status word contains the DSW 


CE.IER I/O Termination error 
Second status word contains the IOSB first word 


CE.IEA Internal error 


Notes: 


The driver drops DTR and RTS when CCHNG executes. 


2.2.2.11 Transmit Data (CCTXD) - This routine transmits a data buffer 
to the destination system at the other end of a communication line. 
The routine delivers the data to the remote system as a character 
string with no intermediate line protocol. 
Formats: 

CCTXD (status, lun, efn, iosb, stadd, size) 
Status A two-word status block as described in Section 2.1.1. 


lun The logical unit number for the communication line. 


efn An event flag the system sets on completion of the operation, 
or zero if you perform the operation synchronously. 


iosb A double-length array used for the IOSB. 


stadd A buffer that contains the data to be transferred. 


size An integer specifying the amount of data to be transferred. 
Status: 

CS.SUC Successful 

CE.PRM Service call parameter error 

CE.DIR © RSX Directive error 


Second status word contains the DSW 


CE.IER I/O Termination error 
Second status word contains the IOSB first word 


CE.IEA Internal error 
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2.2.2.12 Receive data (CCRXD) - This routine reads data from a 
communication line. You can either read all the data currently 
buffered in the driver or wait a specific period of time and read all 
the data accumulated up to that point. Alternatively, you can read a 
fixed amount of data from the line. Input always terminates when your 
buffer becomes full. The driver has a limited amount of buffer space. 


If you specify XON/XOFF support, the driver transmits XOFF when the 
buffer becomes three-quarters full XON when the buffer is emptied to 
the one-quarter point. 


If the buffer becomes full, additional characters are lost. Note that 
the amount of data received is in the second word of the IOSB. 


Format: 

CCRXD (status, lun, efn, iosb, stadd, size, tmo) 
status A two-word status block as described in Section 2.1.1. 
lun The logical unit number for the communication line. 


efn An event flag the system sets on completion of the operation, 
or zero if you perform the operation synchronously. 


10sb A double-length array for the IOSB. 
stadd A buffer into which the routine can place the data. 
size An integer specifying the input buffer size. 


tmo If you do not specify this parameter, input is not complete 
until ‘size’ characters have been written to the buffer. 


If '‘tmo’ is zero, the request returns immediately after 
transferring as many characters as are available up to the 
input buffer size. If ‘tmo’ is not equal to zero, the request 
completes after the time out period specified. See CCDIAL for 
the format of ‘tmo.’ 


Status: 
CS .SUC Successful 
CE.PRM Service call parameter error 
CE.DIR RSX Directive error 
Second status word contains the DSW 
CE.IER I/O Termination error 


Second status word contains the IOSB first word 
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CE.IEA Internal error 


Notes: 


In either of the DTMF modes, the touch tone keys are presented as data 
characters. Further, in CODEC mode the use of the touch tone keys is 
signaled via an auxiliary keyboard, unsolicited input AST. 


2.2.2.13 Flush Input Buffer (CCFLSH) - This routine flushes the input 
buffer for the specified communication line. 


Format: 
CCFLSH (status, lun) 


status A two-word status block as described in Section 2.1.l. 


lun The logical unit number for the communication line. 
Status: 

CS.SUC Successful 

CE.PRM Service call parameter error 

CE.DIR RSX Directive error 


Second status word contains the DSW 


CE.IER I/O Termination error 
Second status word contains the IOSB first word 


CE.IEA Internal error 


2.2.2.14 Generate Break (CCBRK) - This routine generates a break or a 
long space on the line. 


Format: 
CCBRK (status, lun, brk) 


status A two-word status block as described in Section 2.1.1. 


lun The logical unit number for the communication line. 
brk Specify 0 to send a break. Specify 1 to send a long space. 
Status: 
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CS.SUC Successful 
CE.PRM Service call parameter error 
CE.DIR RSX Directive error 


Second status word contains the DSW 


CE.IER I/O Termination error 
Second status word contains the IOSB first word 


CE.IEA Internal error 


2.2.2.15 Kill Transfer (CCKILL) - This routine kills any outstanding 
transfers. You can use it only with asynchronous I/O transfers. The 
outstanding transfer terminates in the normal manner (the system sets 
the event flag you specified at initiation). 
Format: 

CCKILL (status, lun) 


status A two-word status block as described in Section 2.1.l. 


lun The logical unit number for the communication line. 
Status: 

CS.SUC Successful 

CE.PRM Service call parameter error 

CE.DIR RSX Directive error 


Second status word contains the DSW 


CE.IER I/O Termination error 
Second status word contains the IOSB first word 


CE.IEA Internal error 
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2.3 PRO/COMMUNICATIONS SERVICES 
PRO/Communications services consist of: 
@® an application that you can invoke from the P/OS menu system. 


@® a set of utility programs that you can call from your’ application 
program. 


@® a set of routines that allow you to perform Phone Book and File 
Transfer operations. 


As with the Base System Services, you can access PRO/Communications 
services by calling the COMLIB routines. 


The following sections describe PRO/Communications startup, the 
utility programs you can execute, and the routines that allow you to 
perform Phone Book and File Transfer operations. 


2.3.1 PRO/Communications Startup 


When you install PRO/Communications on the Professional, the system 
automatically copies the utility programs to the directory [ZZCOMM], 
together with menu, message and help files. Also during installation, 
the system creates a directory to hold the PRO/Communications 
application. This application generates a menu through which you’ can 
select the various utility programs. 


Once you have installed PRO/Communications on your system, every time 
you power up a Professional and boot P/OS, a PRO/Communications 
Startup Program executes. It performs the following operations: 


@® loads the TMS driver, if you have installed the TMS hardware on 
the system 


@e sets up the default line characteristics for the TMS lines 
@® starts up the background File Transfer Subsystem. 


The PRO/Communications Startup Program is present on your system only 
if you have installed PRO/Communications. 


2.3.2 PRO/Communications Utility Programs 
Any application program can use the PRO/Communications utilities. ig 


you install PRO/Communications on the machine, the system installs all 
utility programs as part of the startup procedure. 
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The utility programs supplied with PRO/Communications are: 


® Communications Setup - allows the user to specify parameters’ that 
control the functioning of the communications services. To allow 
users to change the parameters, your application program can 
either invoke this utility or call the Base System routines. 


@® Terminal Emulator - allows the Professional to act as a vTl102, 
VT125, VT52 or native mode terminal connected to a host operating 
system. Your program can invoke the terminal emulator to allow 
the user to communicate with a host system. The host system, in 
turn, can terminate the emulator and return control to the 
application. 


@® Call Services - allows users to dial and answer calls, using 
either TMS or an $autodial modem attached to the Communication 
Port. This utility runs a call control task that you can use _ to 
make connections via entries stored in the Phone Book. 


@® Phone Book Maintenance - allows users to maintain the phone book. 
The phone book is a file containing information about how to 
connect a Professional 350 to another computer system. Note that 
the routines you can use to access the phone book do not allow 


maintenance. The phone book runs two programs as tasks: a file 
Maintenance program and a server program that reads or displays 
entries in the phone book. You can call the server program 


through the phone book services. 


Each of the utility programs has a user. interface. See the 
Pro/Communications Manual for a description of the utilities and their 
user interfaces. Also, see the Terminal Subsystem Manual for 
additional details on the terminal emulator. 


You use the CCSPWN routine (see below) to make a request to initiate a 
utility. 


2.3.2.1 Spawn Communications Utility (CCSPWN) - This routine spawns a 
PRO/Communications utility task. On termination the routine returns 
the exit status to the requestor. 
Format: 

CCSPWN (status, name) 


status A two-word status block as described in Section 2.1.l. 


name A four-byte string that identifies the requested utility. 
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EMUL Terminal Emulator 

CSET Communications Setup 

CALL Call Services 

PHNE Phone Book Maintenance 
Status: 
CS.SUC - Successful 
CE.PRM - Service call parameter error 
CE.DIR - RSX Directive error 

Second status word contains the DSW 

CE.IEA - Internal error 
Notes: 


In the case of a successful return, the routine returns the exit 
status of the utility in the second status word, as follows: 


: - Successful 

2-4 - Error exit 

5=9 5 = Unused 

o% = MAIN SCREEN key was used to terminate program 
1:0: - EXIT key was used to terminate program 


2.3.3 Phone Book Services 


The services described in this section allow an application to read 
specified entries from the phone book, or display the phone book and 
allow the user to select an entry. To perform phone book maintenance, 
you must use the phone book maintenance program. 


2.3.3.1 Get Phone Book Record (CPHREC) - This service returns a 
specified record from the phone book. 


Format: 
CPHREC (status, name, number, numlen, descr, descrlen, ldb) 
status A two-word status block as described in Section 2.1.1. 
name A 15-byte, space-filled string in which you specify the name 
of the entry to be retrieved. 
number A string in which the routine returns the telephone number. 
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The string can be up to 48 bytes. 


numlen An integer the routine returns indicating the length of the 
telephone number. 


descr A string in which the routine returns the description stored 
in the phone book. The string can be up to 40 bytes. 


descrlen The length of the description string. 
ldb The line descriptor block, a 16-element byte string in which 


the routine returns the line characteristics required to set 
up the call. 


Status: 
CS.SUC - Successful 
CE.PRM - Service call parameter error 
CE.DIR - RSX Directive error 
Second status word contains the DSW 
CE.IER - I/O Termination error 
Second status word contains the IOSB first word 
CE.NNF - Name not found 
CE.IEA - Internal error 
Notes: 


If you call this routine with a blank name parameter, it functions 
identically to CPHSEL. 


2.3.3.2 Select Phone Book Entry (CPHSEL) - This service displays all 
the phone book entries and allows the user to select a specific entry 
from those available. 


Format 
CPHSEL (status, name, number, numlen, descr, descrlen, ldb) 
status A two-word status block as described in Section 2.1.1. 
name A 15-byte string in which the routine returns the name of 
the entry to be retrieved. 
number A string in which the routine returns the telephone number. 
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The string can be up to 48 bytes. 


numlen An integer the routine returns indicating the length of the 
telephone number. 


descr A string in which the routine returns the description stored 
in the phone book. The string can be up to 40 bytes long. 


descrlen The length of the description string. 
ldb The line descriptor block, a 16-element byte string in which 


the routine returns the line characteristics required to set 
up the call. 


Status: 
CS<Suc - Successful 
CE.PRM - Service call parameter error 
CEsDIR - RSX Directive error 
Second status word contains the DSW 
CE.IER - I/O Termination error 
Second status word contains the IOSB first word 
CE.NNF - Name not found 
CE.IEA - Internal error 
CE.CTB - CTAB display error (empty phone book) 


2.3.4 File Transfer Services 


This section describes services that allow you to use the File 


Transfer Subsystem. Using the File Transfer Subsystem, you can 
transfer files between Professionals through callable service 
routines. (Note that PRO/Communications already includes a 


Professional-to-Professional file transfer application, which itself 
uses the File Transfer Subsystem.) 


The File Transfer Subsystem consists of the following components: 


® Communications Manager Program - controls the initiation and 
termination of the file transfer programs. 
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@e File Transfer Server - executes in response to a request from 
another system tO initiate a file transfer. The server 
communicates with the "host" program to perform a file transfer. 
The host program currently runs on RSX-11M/11M+, VMS or the 
Professional. 


e File Transfer Host Program - initiates a file transfer. Rs 
communicates with the server program. 


@® Listener Program - monitors the following communication lines in 


the background: the Communication Port, TMS line 1 and TMS line 
2. The program monitors lines in data mode only for ASYNC 
transfers. When the Professional receives unsolicited ASYNC data 


over a monitored line, the listener program attempts to interpret 
the data as an ANSI escape sequence, provided the line is not 
currently attached and no outstanding reads are present. The 
listener processes only file transfer requests. 


You can initiate a file transfer to the Professional either when the 
Professional is in terminal emulation mode or when the listener 
intercepts the file transfer escape sequence. The latter case 
constitutes a background transfer. 


The File Transfer Subsystem always runs asynchronously in the 
background; however, the program issuing calls to it can either 
synchronize with each call to the Susbsystem or run file transfer 
operations asynchronously. 


2.3.4.1 File Transfer Initiation Protocol - Receipt of the escape 
sequence initiates file transfer. The escape sequence is: 


Pb 


ESC: [ :1 3! 


Prior to sending the escape sequence, the file transfer host program 
tries to determine if the Professional is able to perform the 
transfer. It does this by sending a device status request (DSR): 


ESC [ 5 n 


The Professional must respond with a "ready, no malfunctions" response 
reports 


ESC [ On 


After accepting the file transfer escape sequence, your application 
should request the file transfer server task. At the end of the file 
transfer, a further DSR escape sequence will be received and the 
“ready, no malfunctions" report described above must be returned. 
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2.3.4.2 Attaching the file transfer Subsystem - In order to initiate 
a file transfer, the requesting task must attach the File Transfer 
Subsystem. This applies both to transfers initiated by the local 
system and requests to activate the server in response to requests 
from a remote system. Because of processor limitations, only one file 
transfer can be active in the system at any time. If another task has 
alread attached the File Transfer Subsystem, the Subsystem rejects 
further requests for attachment. The process of attachment informs 
the File Transfer Subsystem of the line on which it performs’ the 
transfer. Also, attachment can optionally send a password to the 
remote system (if the local system is the initiator). 


2.3.4.3 Releasing the file transfer Subsystem - You automatically 
release the File Transfer Subsystem upon terminating the task that 
attached it. Also, you can explicitly request the release of the 
Subsystem (using the FTDET routine) . Note that any queued requests 
continue to be processed even if you have released the Subsystem. 


2.3.4.4 Synchronous and Asynchronous Operations - A program that 
initiates an operation to the File Transfer Subsystem has two options. 
Tt either can wait for the operation to complete, or can synchronize 
with the return message at a later point in time. This is called an 
asynchronous operation; you can use it to initiate multiple file 
operations. 


Each call to the file transfer services (except FTDET) resultS in a 
message sent to the File Transfer Subsystem. For each message sent, 
the Subsystem returns a response to the requesting task (unless 
suppressed). You can synchronize these responses’ by calling the 
FTSYNC routine. Use the ‘msgid’ parameter to identify the response to 
the requesting task. 


2.3.4.5 File Transfer Synchronization - The file transfer service 
calls contain 'reply' and 'sync' parameters to enable synchronization 
between your application program and the File Transfer Subsystem. 
Calls to the file transfer routines that contain a ‘reply’ parameter 
cause action messages to be sent to the File Transfer Subsystem. The 
Subsystem generates response messages depending on the value you 
specify for 'reply.' These messages are passed using the variable 
send/receive data directives. You can synchronize the caller with 
response messages from the Subsystem by either setting the ‘sync’ 
parameter when issuing a call and setting the reply flag to 2 (running 
the Subsystem synchronously), or calling the FTSYNC routine, which 
also uses the ‘sync’ parameter. 
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In either case, setting the 'sync' flag causes the calling task to 
stop for a response message from the File Transfer Subsystem. The 
user's impure data area holds the response; you can access it by 
calling FTUNPK. 


The possible values for 'reply' are: 


Bit(s) Value Meaning 
SS Ne eran sea nam ene ee ge oe A I eae DO TE OO ee eae a ee 
O-1 0 No response message. 
i Response message requested. 
2 Response message and unstop requested. 
File Transfer Subsystem will issue unstop 
directive for requesting task. You 
must use this value if sync flag = l. 


Do not write message to system message board. 
Write message to system message board. 

Write message to system message board only 

on error. 

3 Write message to system message board only 

if successful. 


Nor © 


3-15 Reserved. 
NOTE 
The File Transfer Subsystem writes messages to. the 


system message board when a task that has requested a 
response message has exited. 


2.3.4.6 Set Up File Transfer Options (FTOPTG and FTOPTP) - Two 
routines allow you to configure the file transfer options’ for 
automatic file transfer initiated by a remote system. The routine 
FTOPTG returns the current option settings; the routine FTOPTP 
modifies the current option settings. 
Formats 

FTOPTG (status, flags, pswrd, vol, direc, max file) 

FTOPTP (status, flags, pswrd, vol, direc, max_file) 
status A two-word status block as described in Section 2.1.1. 


flags Option Flags: 


bit 0 1 Enable remote file copy 
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pswrd 


vol 


direc 


max file 


Status: 
CSsSUCc 
CE.PRM 


CE.RMS 


CE.IEA 
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0 Disable remote file copy 


bit 1 1 =Enable remote file receive 
0 Disable remote file receive 


bit 2 1 Supersede existing files 
O Do not supersede existing files 


bit 3 1 Enable password security 
O Disable password security 


bit 4 1 Local delete enabled 
0 Local delete disabled 


Bits 5 through 15 are reserved. 


A nine-character password to be used by a remote 
Professional. It must be space filled if you have disabled 
password security. 


A 12-character name of the volume to which the File Transfer 
Subsystem places files received from another Professional. 
The Subsytem uses this parameter only if the incoming file 
specification contains no volume specification. 


A nine-character name of the directory into which the File 
Transfer Subsystem places files being received from another 
Professional. The Subsystem uses this parameter only if the 
incoming file specification contains no directory 
specification. 


A double-length integer specifying the maximum size, in 


blocks, of a local file that the remote Professional can 
create. Note that a zero value indicates no limit. 


Successful 
Service call parameter error 


File I/O error 
PRO/RMS-11 error code passed in second word 


Internal error 


NOTE 


These routines perform file I/O to the communications 
setup data file. (This file stores default line 
characteristics, translate tables, and other 
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information used by the communications services.) In 
order to perform the file I/0, you must assign a 
logical unit number’ to the setup data file. You do 
this by inserting the following global definition 
command in your PAB command (.CMD) file: 


GBLDEF = CM SLUN:lun 


lun is the logical unit number that the system 
associates with the communications setup file. 


See the section on command files in this manual for 
Further information. Also, see the description of 
GBLDEF in the RSX-1LIM/M-PLUS Task Builder Manual. 


2.3.4.7 Attach File Transfer Subsystem (FTATT) - This routine 
attaches the designated line to the issuing task for use with the File 
Transfer Subsystem. You must call this routine prior to invoking any 
of the other File Transfer Subsystem routines, except as noted in the 
routine definitions. The issuing task can optionally specify a 
password to gain access to the remote system. 


Formats: 


status 
dev 
unit 
reply 


msgid 


sync 


PSWD 


paswrd 


FTATT (status, msgid, reply, sync, dev, unit, ‘'PSWD', paswrd) 
A two-word status block as described in Section 2.1.1. 

A two-byte ASCII string containing the device mnemonic. 

The unit number. 

A reply flag. 


An unsigned integer that identifies the return message for 
this call. 


A synchronization flag: an integer that determines whether or 
not the calling program will stop if no response message is 


queued. 


0 - Do not stop for response 
1 - Stop for response message 


An optional keyword that specifies the presence of a password 
parameter immediately following. 


A optional nine-byte string containing the password for’ the 


2=30 


PRO/COMMUNICATIONS SERVICES 


remote system, space-filled. You must immediately precede 
this parameter with the PSWD keyword. 


Status: 
CS .SUC - Successful 
CE.PRM - Service call parameter error 
CE.DIR - RSX Directive error 
Second status word contains the DSW 
CE.IEA - Internal error 
Notes: 


If a task issues to calls to FTATT without an intervening call to 
FTDET, an error occurs on the second call to FTATT. 


2.3.4.8 File transfer Operation Request (FTOPRN) - This routine 
issues file operation requests to the File Transfer Subsystem. The 
routine allows you to: transfer files between systems, determine the 
Status of file transfers currently in progress, or abort the current 
transfer. You can specify only one file operation request in any call 
to the routine. 


Formats: 
FTOPRN (status, msgid, reply, sync, request) 


The format of a request is: 


status A two-word status block as described in Section 2.1.1. 


msgid An unsigned integer that identifies the return message for 
this call. 


reply Reply flags. 


sync synchronization flag: an integer that determines whether or 
not the calling program will stop if no response message is 
queued. 


ABRT 


STAT 


SEND 


READ 


fspecl 


lenl 


Fspec2 


len2 


DELE 


fspecl 


lenl 


Status: 


CS.SUC 


CE.PRM 


CE.UNO 


CE.MFE 


CE.IMO 
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0 - Do not stop for response 


1 - Stop for response message 

allows you to abort the current file operation. If no file 
operation is in progress, the routine returns an error in the 
‘status’ parameter. 

causes the routine to return statistics on the current file 
transfer operation to the caller. YOu can access’ the 
statistics via the FTUNPK routine. 

allows you to transfer files to the remote system. You can 
use only a single file specification (no wild cards). 

allows you to transfer files from the remote system. You can 


use only a single file specification (no wild cards). 


A string buffer holding the file specification of the file to 
be transferred. 


The length of ‘fspecl.' 


A string buffer holding the destination file specification of 
the file to be transferred. 


The length of 'fspec2.' By default, the destination file has 


the same name and type as ‘'fspecl.' If no change is required, 
‘len2' should be zero. If you want to place the file on a 
specific device or ina specific directory, you must specify 
‘'fspec2'; otherwise, the routine uses the system's default 
destination. 


allows you to delete a file at a remote system. You can 


specify only a single file specification (no wild cards). 


A string buffer holding the file specification of the file to 
be deleted. 


The length of 'fspecl.' 

- Successful 

- Service call parameter error 
- Unsupported message option 

- Message format error 


- Operation Rejected 
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CE.MSC - Message type out of sync 
CE.DDC -  DDCMP error 
CE.RMS - File I/O error 
RMS Error code passed in second word. 
CE .NFT - No file transfer 
CE.IEA - Internal error 


f 
sf 


2.3.4.9 Notify On Incoming File (FTNTFY) - This routine requests’ the 
File Transfer Subsystem to notify a specified task when a file is 
received from a remote system. Upon arrival of each file, the 
Subsystem sends a duplicate of the response message that it returns to 
the task requesting the server activation. This indicates the full 
specification of the incoming file and termination statistics. 


Format: 


FTNTFY (status, msgid, reply, sync, notify, 
'TASK', taskid, ‘'CNCL') 


status A two-word status block as described in Section 2.1.1. 


msgid An unsigned integer that identifies the return message for 
this call. 


reply Reply flags. 


sync Synchronization flag: an integer that determines whether or 
not the calling program stops if no response message is 
queued. This parameter applies only to the File Transfer 
Subsystem'’s initial verification to indicate acceptance of the 


request. 
0 - Do not stop for response 
1 - Stop for response message 


notify Notification flag: an integer that determines how the File 
Transfer Subsystem notifies the task that the specified file 
has arrived. 


1 - Send the notification message to the specified task. 
2 - Send notification message and unstop the specified task. 
3 - Send the notification message using the request and 
connnect directive. 
TASK requests the File Transfer Subsystem to direct notification 
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messages to the task specified in ‘'taskid'. If you omit this 
option, the routine by default uses the current task name. 


taskid Task to be notified in RAD50O format 


CNCL cancels previous requests for file transfer notification. The 
only other optional parameter that you can use with 'CNCL’' is 
'TASK.' 

Status: 

CS.SUC - Successful 

CE.IMO - Operation Rejected 

CE.PRM - Service call parameter error 

CE.IEA - Internal error 

CE.DIR - RSX Directive error 


Second status word contains the DSW 
Notes: 


The File Transfer Subsystem sends response messages to the specified 
task. You can interpret these messages by using the FTSYNC and FTUNPK 
routine to access the file name and termination statistics of the file 
received. Setting the ‘sync’ flag when calling FTSYNC requires having 
used a notification flag = 2. The original 'msgid' you specify when 
calling FTNTFY is preserved in all subsequent notification messages. 
The task being notified need not be active. 


2.3.4.10 Synchronize with file transfer (FTSYNC) - Use this’ routine 
to synchronize your task with an asynchronous request previously 
issued by a call to FTATT, FTDET, FTOPRN or FTNTFY. It places a 
response message from the File Transfer Subsystem into the calling 
program's impure data area. You should immediately unpack’ the 
response message by calling FTUNPK. 
Formats 

FTSYNC (status, msgid, sync) 
status A two-word status block as described in Section 2.1.1. 


msgid A message identifier that the File Transfer Subsystem returns. 
You pass this parameter in the original call. 


sync Synchronization flag: an integer that determines whether’ the 
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program stops if no message is currently queued. 


0 - Do not stop. 

1 - Stop for response message. 
Status: 
CS.SUC - Successful 
CE.PRM - Service call parameter error 
CE.IMO - Operation Rejected 
CE.STU - File transfer startup in progress 
CE.IEA - Internal error 


2.3.4.11 Unpack File transfer message area (FTUNPK) - This’ routine 
unpacks the message components from the impure data area. You specify 
each message component with a keyword. Note that the calling’ task 
need unpack only those components that are of interest to it. You 
must immediately precede a call to FTUNPK with a call to FTSYNC. 


NOTE 


Any call to the other communication service routines 
between calls to FTSYNC and FTUNPK can overwrite the 


response message held in the application's impure data 
area. 


Formats: 


FTUNPK (status, — E', filesize, 
" FILE’ » Espec, — 
*BLCK', bicknum, © 
"DEVC’', Gey, 
‘UNIT’, un. 
‘TIME’, elps tim, 
*OPER’, Prccourn ) 


status A two-word status block as described in Section 2.1.1. 


SIZE returns a double-length integer indicating the size of the 
file you are transferring. 


filesize A double-length integer into which the routine places’ the 
file's size. 


FILE 


Espec 


len 


BLCK 


blcknum 


DEVC 


dev 

UNIT 
unit 
TIME 


elpstim 


OPER 


operation 


Status: 


CS.SUC 


CE.PRM 


CE.IMO 


CE.MSC 


CE.IEA 
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returns the name of the current file on which you are 


performing the file operation. 


place the file 
This buffer 


A buffer into which the routine can 
specification of the file being transferred. 
should be at least 50 bytes long. 


The length of the file specification returned in the 'fspec' 
buffer. 


returns the current block number of the file you are 


transferring. 


A double-length integer that receives the current’ block 
number of the file you are transferring. 
option returns the device mnemonic for the current’ file 


operation. 

A two-byte ASCII string that receives the device mnemonic. 
returns the unit number for the current file operation. 

An integer that receives the unit number. 

returns the elapsed time for the current file transfer. 


A double-length integer that receives the elapsed time in 


seconds. 
returns the current file operation. 


A single-length integer that receives the code for the 


operation in progress: 


- READ 
- SEND 
LOCAL DELETE 
REMOTE DELETE 


Hm GN) Fe 
1 


-~ Successful 

- Service call parameter error 
- Operation Rejected 

- Message type out of sync 


- Internal error 
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2.3.4.12 Detach File Transfer (FTDET) - This routine detaches’ the 
File Transfer Subsystem from use by the requesting task. 


Formats: 
FTDET (status, msgid, reply, sync) 
Status A two-word status block as described in Section 2.1.l. 


msgid An unsigned integer that identifies the return message for 
this call. 


reply Reply flags. 


Status: 
CS.SUC - Successful 
CE.PRM - Service call parameter error 
CE.DIR - RSX Directive error 

Second word contains the DSW 
CE.IEA - Internal error 


2.3.4.13 Start File Transfer Server (FTSERV) - This routine requests 
the file transfer server on the local system. You should call this 
routine in conjunction with initiation of the host file transfer 
program. 
Formats: 

FTSERV (status, msgid, reply, sync) 


status A two-word status block as described in Section 2.1.1. 


msgid An unsigned integer that identifies the return message for 
this call. 


reply Reply flags. 


sync Synchronization flag: an integer that determines whether or 
not the calling program will stop if no response message is 
queued. 
0 - Do not stop for response message 
1 - Stop for response message 

Status: 
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CS.SUC - Successful 

CE.PRM - Service call parameter error 

CE.UNO - Unsupported message option 
 CE.MFE - Message format error 

CE.IMO - Operation Rejected 

CE.MSC - Message type out of sync 

CE.DDC - DDCMP error 

CE.RMS - File I/O error 

RMS Error code passed in second word. 
CE.NFT - No file transfer 
CE.IEA - Internal error 


2.3.4.14 Enable/Disable File Listening (FTLISN) - Calling this 
routine with the enable flag set causes the File Transfer Subsystem to 
monitor an unattached line for unsolicited data. The listener program 
reads unsolicited data from the specified line. Upon receiving a 
valid file transfer request, the listener automatically initiates a 
file transfer. 


Note that other applications can ATTACH or DETACH the File Transfer 
Subsystem; however, the listening task will not be able to initiate 
file transfers while the Subsystem is attached. 

Format: 


FTLISN (status, dev, unit, flag) 


Status A two-word status block as described in Section 2.1.l. 


dev A two-byte ASCII string containing the device mnemonic. 
unit The unit number. 
flag A flag that indicates the type of request: 


0 - Disable listening 
1 - Enable listening 


Status: 
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CS.SUC - Successful 
CS.FLE - File listening already enabled with enable request 
CS.FLD - File listening already disabled with disable request 
CE.PRM - Service call parameter error 
CE.DIR - RSX Directive error 
Second word contains the DSW 
CE.IEA - Internal error 
Note: 


If you call FTLISN with just the status parameter, the second status 
word contains the current listener’ status. Bit zero set means 
listening is enabled on XKO:. 


2.4 TELEPHONE MANAGEMENT SYSTEM (TMS) SERVICES 


This section describes services that enable your application program 
to control the TMS hardware. 


Note the following if you are using CODEC input on a TMS line: TMS 
digitizes the voice signal at 4 kilobytes per second, and so you will 
lose voice data unless you perform asynchronous I/O and double buffer 
the input requests. Each input request should specify a 4 kilobyte 
buffer; this provides 1 second for your application to process’ the 
first buffer before the second buffer fills. 


The following sections describe TMS startup and the TMS routines. 


2.4.1 TMS Startup 


The PRO/Communications application handles TMS~ startup. See the 
section on "PRO/Communications Startup" earlier in this chapter for 
details. 


2.4.2 TMS Routines 


This section describes the routines that you can call to control the 
operation of the TMS hardware. Note that you must have installed the 
hardware in order to call any of the routines. 
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A211 Change Mode (CCMODE) - This routine changes the current mode 
of the line. The line must be attached. Also, the mode change does 
not take effect until you issue a CCANS or CCORG call. 
Format : 

CCMODE (status, lun, mode) 


Status A two-word status block as described in Section 2.l.l. 


lun The logical unit number for the communication line 
mode One of the following available mode settings: 
O = VOICE 
aE = ASYNC (Modem) 
2 = CODEC 
3 = DTMF Keypad (Touchtone pass all keys) 
Status: 
CS.SUC - Successful 
CE.PRM - Service call parameter error 
CE.DIR - RSX Directive error 
Second status word contains the DSW 
CE.IER - I/O Termination error 
Second status word contains the IOSB first word 
CE.IEA = Internal error 
Note: 


After calling CCMODE, if you want to change the current mode to ASYNC, 
you must establish a connection by calling CCORG. In the case where 
your application will be communicating with another TMS unit, one unit 
must be in originate mode (using CCORG) and the other TMS unit must be 
in answer mode (using CCANS). 


2.4.2.2 Auxiliary Keyboard Enable/Disable (CCAUXK) - This’ routine 
enables or disables the auxiliary keyboard for the specified TMS line. 
The line must be attached. An AST trap signals input from the 
auxiliary keyboard. You must use the CCATA routine to attach the 
line. 


Formats 


status 
lun 


flag 


Status: 
CS.SUC 
CE.PRM 


CE.DIR 


CE.IER 


CE.IEA 
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CCAUXK (status, lun, flag) 
A two-word status block as described in Section 2.1.1. 
The logical unit number for the communication line 


This flag indicates whether the keyboard is 
enabled/disabled: 


0 - Disabled 
1 - Enabled 
- Successful 


- Service call parameter error 


- RSX Directive error 
Second status word contains the DSW 


- I/O Termination error 


Second status word contains the IOSB first word 


- Internal error 


Prepare to Go Voice (CCPTGV) - This routine warns 


specified TMS line that it is about to go into VOICE mode. 


not disconnect the call when the change in mode occurs. 


be attached. 


Format: 


status 


Pun 


Status: 


CS.SUC 


CE.PRM 


CE.DIR 


CCPTGV (status, lun) 
A two-word status block as described in Section 2.1.l. 


The logical unit number for the communication line 


- Successful 
- Service call parameter error 


- RSX Directive error 
Second status word contains the DSW 
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being 


the 


TMS does 
The line must 
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CE.IER - I/O Termination error 
Second status word contains the IOSB first word 
CE.IEA - Internal error 
Notes: 


You can call CCHNG to cancel CCPTGV and disconnect the telephone line. 


2.4.2.4 Set DTMF escape sequence (CCDTMF) - This routine sets a DTMF 
escape sequence on the specified TMS line. The routine returns an 
unsolicited event AST trap upon ecountering the sequence. CCDTMF 
reports this by setting an event flag if you have used CCATA to attach 
the line. The line must be attached. 
Format : 

CCDTMF (status, lun, dtmf, dtmflen) 
status A two-word status block as described in Section 2.1.1. 


lun The logical unit number for the communication line 


dtmf A string that contains the DTMF escape sequence. The string 
terminates with a zero byte. 


dtmflen The length of the DTMF escape sequence. 


Status: 
CS.SUC - Successful 
CE.PRM - Service call parameter error 
CE.DIR - RSX Directive error 
Second status word contains the DSW 
CE.IER - I/O Termination error 
Second status word contains the IOSB first word 
CE.IEA - Internal error 


CHAPTER 3 


FAST INSTALL 


Fast Install is a Professional 350 application that allows you _ to 
install an application from a directory on the hard disk. (P/OS 
Disk/Diskette Services can install an application from diskette only.) 
Fast Install is distributed with the Host Tool Kit and the PRO/Tool 
Kit on the Application Diskette Builder (ADB) diskette. 


To use Fast Install, follow these steps: 


1. If you have not already installed Fast Install on your 
Professional, do so now. Insert the ADB diskette, select 
Disk/Diskette Services, and select Install Application. When 
finished, remove and store the diskette. 


2. Select Fast Install from the menu on which it was installed. 


3. Fast Install prompts for the name of your application directory. 
Enter it and press DO. 


4. Fast Install opens the .INS file and checks the format. Lf 2at 
finds no errors, Fast Install displays a single-choice menu 
consisting of a list of P/OS menus. Select the menu on which you 
wish to install your application and press DO. 


5. After successful installation, you can run your application from 
the P/OS user interface. 


Notes: 


@® Fast Install will install P/OS Diskette applications only if the 
REQUIRE, OPTIONS, and LOAD lines are commented out. Remember that 
you will then be testing a P/OS Diskette application on aé_ hard 
disk system. 


@® If the application directory is not found, or does not not contain 
an installation command (.INS) file with the same name, 
installation fails. 


If a PRO/RMS-11 record error occurs while Fast Install is opening 
the .INS file, look up the error code in the PRO/RMS-11 manual 
set. If you cannot correct the problem, submit a Software 
Performance Report (SPR) to DIGITAL; be sure to include the 
PRO/RMS-11 error code. 


If the .INS file contains an error, Fast Install prints one of the 
error messages shown in Appendix A. Fast Install and _ the 
Application Diskette Builder parse installation commands the same 
way and thus use the same error messages. 


CHAPTER 4 


FILE CONTROL SERVICES (FCS) 


File Control Services (FCS) is a set of file management routines’ for 
use on the RSX-11 family of operating systems. It was designed for 
the RSX-11D operating system in the early 1970s, and has’ been 
implemented subsequently for IAS, RSX-11M, RSX-11M-PLUS, the RSX 
Application Migration Executive on VMS, and for the RSX run-time 
system on RSTS/E. FCS can be considered the precursor of Record 
Management Services (RMS-11), which is implemented on all of the above 
systems as well as on P/OS (PRO/RMS-11). 


NOTE 


FCS is described in detail in the IAS/RSX-11 I/0 


Operations Reference Manual that is part of the 
RSX-11M/M-PLUS documentation set. 


Originally, P/OS applications could use only PRO/RMS-11 for file 
system operations. All applications targeted for P/OS had to use 
PRO/RMS-11. Applications which had been written to use FCS had to be 
converted to use PRO/RMS-11 instead. 


With the release of the PRO/Tool Kit V1.0 and the Host Tool Kit V1.7, 
the FCS routine library became part of the P/OS system module library. 
Tool Kit V2.0 includes a vectored FCS resident library. Thus, you can 
move applications that use FCS to P/OS without conversion to 
PRO/RMS-11. 


FCS is included in the Host and PRO/Tool Kits only for the purpose of 
moving existing applications to P/OS. Other than this chapter, FCS 
not described in the Tool Kit documentation set. Use PRO/RMS-11 when 
you write new applications. 


FCS does not support as many features of P/OS as PRO/RMS-11l. DIGITAL 
will enhance P/OS and PRO/RMS-11 but will not add these enhancements 
to ECS. These improvements will likely occur in the areas of 
networks, logical name handling and the file system. Programs using 
FCS will not be able to take advantage of these enhancements. 


FEATURES SPECIFIC TO FCS ON P/OS 


4.1 FEATURES SPECIFIC TO FCS ON P/OS 


FCS for P/OS includes several features not in FCS for RSX-11M_ and 
RSX-11M-PLUS. The names in parentheses following each feature 
identify the modules which have been modified to support the feature. 
Other modules are the same as in FCS for RSX. 


1. Named directories (ASCPPN, DIDFND, DIFND, DIRFND, PARDI, PARSDI) 


P/OS uses directory names consisting of one to nine alphanumeric 
Characters in the set A to Z, 0 to 9. FCS uses these directory 
names also. 


The P/OS "current directory", the directory implied if a directory 
name iS not explicitly specified, is also used by FCS. 


In addition to named directories, FCS also recognizes numeric 
directories in User Identification Code (UIC) form. 


Square or angle brackets can enclose directory specifications. 
2. Logical device names (PARSDV) 


FCS translates P/OS logical names for devices, volume names’- for 
example, to the appropriate physical device name. However, FCS 
does not translate logical names which are not in the form of 
device names. 


3. VMS-style version numbers (CBTA, ODCVT, PARSFN) 


FCS for P/OS uses version numbers in the decimal radix (as opposed 
to octal radix). Version numbers can be separated from file types 
by a period (or dot ".") or by a semicolon. 


4. Other differences (FCSMAC, FCSPRE) 


To support named directories and logical device names, the File 
Storage Region impure data region (SSFSR2) is larger by 82 bytes 
than its size on RSX systems. 


5. Standard P/OS devices 


FCS supports all the standard P/OS' devices: the dual RX50 
diskette drives as DZl: and DZ2:, the hard disk drive (if any) as 
DWl:, the Professional terminal (keyboard and monitor) as fTTIl:, 
TT: or TI:, and the printer (if any) as LP: or TT2:. The 
Professional monitor is supported as a VT102-compatible output 
device. 


4.2 


LIMITATIONS OF FCS ON P/OS 


LIMITATIONS OF FCS ON P/OS 


Support by higher level languages 


Programs written in MACRO-11 assembly language can use _ FCS. 
Programs written in other Tool Kit languages’ (BASIC-PLUS-2, 
COBOL-81, PRO/DIBOL, FORTRAN-77 and PASCAL) do not work with FCS 
because the Object Time Systems (OTS) of these languages on P/OS 
use PRO/RMS-11 rather than FCS. The RSX versions of some of these 
languages will probably work on P/OS provided that the programs 
are taskbuilt using the Tool Kit version of the System Object 
Module Library (SYSLIB) which includes FCS. Such use is not 
Supported by DIGITAL. 


Other higher level languages available from vendors other than 
Digital may use FCS in their object-time systems. Please refer to 
product documentation of these software products. 

Usage of resident libraries 

Vectored FCS is included with the Tool Kit V2.0. It is compatible 
with the FCSRES for Micro/RSX. A task built against vectored FCS 
will run on either system. 


Support in future releases 


Programs using FCS must be rebuilt to run on new versions of P/OS. 


The 


CHAPTER 5 


FRAME DEVELOPMENT TOOL (FDT) 


Frame Development ’Tool (FDT) is a special-purpose utility for 


creating menu, help, and message frames. These frames, when used with 


the 
P/OS 


POSRES User Interface Library, make up a user interface for your 
application. Designing a user interface and programming with 


POSRES are described in the Tool Kit User's Guide. 


Sel 
FDI 


Ls 
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OVERVIEW 
frame development follows these general steps. 


Plan your frames. You should have a good idea of what frames your 
menu structure and help structure will require before you use FDT. 


Start FDT and specify a file name for the frame definition file. 
If you are creating a new file, specify the type of frames you 
want to create. 


Enter a File Command. You can Add, Delete, List, Modify, Name, 
and Report on frames, or ask for Help. When you are finished with 
the current file, you can Save* the file on disk, Convert it to 
executable format and save it, open another File (saving the 
current file), or Quit, discarding the session. 


Enter a Frame Command. You can enter the Profile form, the 
Display form, or the Action (menus only) form, or ask for Help. 
When you are finished with the frame, you can Save* the frame on 
disk or Quit to return to step 3. 


While entering a form, you can use a special set of keypad keys. 
When you are finished with a form, you press ENTER to return to 
step 4. 


* Exit is identical to Save. 


OVERVIEW 


The following sections describe how to run FDT, the File commands, the 
Frame commands, and the forms in more detail. If you would like to 
try out a sample FDT editing session before moving on, turn to Section 
aaa bea 


5.2 INVOKING FDT ON RSX-11M/M-PLUS (DCL) 
If FDT is installed on your system as "...FDT", type: 
S$ FDT filename 


If you do not specify a file name, FDT prompts for one. The default 
file type is .DAT. 


If FDT is not an installed task, type: 
S$ RUN SFDT 
and specify a file name when FDT prompts. 


If the file does not exist, FDT assumes that you are creating a new 
file and prompts for the type of frame you want the file to contain: 


Create (H)elp, (M)essage, or (S)ingle-choice menu file? 
Enter “HY, “M" Or “Ss 
NOTE 
You can store frames of only one type in ae file. 


Create individual files for help, messages, and 
single-choice menus. 


5.3 INVOKING FDT ON VAX/VMS 


For convenience, edit your LOGIN.COM file and insert the following 
symbol definition: 


Once the symbol is defined, you can invoke FDT by typing: 
S$ FDT filename 


If you do not specify a file name, FDT prompts for one. The default 
file type is .DAT. 


INVOKING FDT ON VAX/VMS 
If the file does not exist, FDT assumes that you are creating a new 
File and prompts for the type of frame you want the file to contain: 
Create (H)elp, (M)essage, or (S)ingle-choice menu file? 
Enter "H", "M", or "S", 
NOTE 
You can store frames of only one type in ae file. 


Create individual files for help, messages, and 
single-choice menus. 


5.4 FILE COMMANDS 


File commands allow you to select alternate frame definition files and 
individual frames. They are entered in response to the prompt: 


File Command: 


With the exception of the QUIT command, you can abbreviate any file 
command to a single character. 


While working at file command level, the current file type and file 
name are displayed in a message at the top of your screen. If you 


enter a command and omit required parameters, FDT displays prompts 
requesting them. 


NOTE 


Do not specify frame identifiers with embedded spaces. 
POSRES cannot retrieve them correctly at run time. 


5.4.1 ADD 


The ADD command allows you to create a new frame, which can be added 
to a new or existing frame definition file. 


Format : 
ADD frameid 


frameid A string of up to eight alphanumeric characters that 
identifies the new frame. 


FILE COMMANDS 


Notes 


@ A frame identifier must consist of alphanumeric ASCII characters. 
FDT converts all characters to uppercase. 


@e If you are editing a help file, FDT prompts as follows: 
Help (M)enu or (T)ext? 
Type "M" for a help menu and "T" for a help text frame. 


@® FDT displays a Profile form, which is the first form you must fill 
in when you ‘are creating a new frame. 


5.4.2 CONVERT 


The CONVERT command creates an executable frame definition file that 
can. be read directly by POSRES menu services during program execution. 


Format : 

CONVERT output-file 
output-file The name of the executable frame definition file. 
Notes: 


e The default file types for converted files are: 


-HLP Help definition file 
~MSG Message definition file 
-MNU Menu definition file 


@e All required fields on frames must be filled in before the frame 
is converted. If a frame lacks required information, an error 
message is displayed and the frame is not converted. 


e FDT displays these messages: 


x frames converted, y frames not converted. 
The largest frame, "<framename>", is n bytes long. 


The numbers x,y, and n are decimal. If there were unconverted 
frames, other messages will appear. 


Record the size of the largest frame converted. You can use this 


number to compute the minimum amount of buffer space required for 
frames of the type stored in this file (see the chapters on _ the 
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FILE COMMANDS 


Professional Application Builder and the P/OS User Interface 
Services in the Tool Kit User's Guide). 


5.4.3 DELETE 


The DELETE command allows you to delete the specified frame from the 
current file. 


Formats: 
DELETE frameid 
frameid The identifier of the frame to be deleted. 


Notes: 


@ Before deleting the frame, FDT shows the Display form for the 
specified frame and prompts: 


Delete this frame? 
If you type "Yes", the frame is discarded; if you type "No", it is 


not. After you respond to the prompt, control returns to the File 
Command prompt. 


5.4.4 EXIT 

The EXIT command saves the current frame definition file on disk; it 
performs the same function as the SAVE command. After saving a file, 
FDT displays a confirmation message naming the file saved and returns 
control to host system command level. 

Formats: 


EXIT 


5.4.5 FILE 


The FILE command allows you to open another frame definition file. 


FILE COMMANDS 


Format: 

FILE filename 
filename The name of the frame definition file. 
Notes: 


@e If you are creating a new frame file, FDT prompts for the type of 
file you want to create: 


Create (H)elp, (M)essage, or (S)ingle-choice menu file? 
Enter "H", "M", or "S", or press return to exit. 


® If you did not save the current file before specifying another 
file, FDT prompts: 


Save current file? 


Type "Yes" to save it, or "No" to discard it. 


5.4.6 HELP 
The HELP command displays a list of FDT file commands. 
Format: 


HELP 


5.4.7 LIST 


The LIST command displays a list of the frames in the current 
definition file by frame identifier. 


Formats: 
LIST 
Notess 
@ The frames are listed in the order they were created, although the 


order may change as a result of the addition or deletion of 
frames. 


FILE COMMANDS 


5.4.8 MODIFY 


The MODIFY command finds the specified frame in the frame definition 
file. 


Formats: 
MODIFY frameid 
frameid The identifier for the frame to be modified. 


Notes: 


@® FDT displays a message indicating the frame is available for 
modification and displays the "Frame Command" prompt. 


5.4.9 NAME 
The NAME command renames a frame. 
Format : 
NAME old-frameid new-frameid 
old-frameid is the frameid that is to be renamed. 


new-frameid is the new name (up to eight ASCII alphanumeric 
characters). 


5.4.10 QUIT 
The QUIT command returns control to host system command level without 
saving the current file. All changes made in the current editing 
session are discarded. 
Format: 

QUIT 


Notes: 


@e All of the characters in the QUIT command must be typed. 


FILE COMMANDS 


5.4.11 REPORT 


The REPORT command creates a printable file containing information 
about each frame in a frame definition file. 


Formats: 

REPORT filename 
filename The name of the output file that will contain the report. 
Notes: 


@ If you do not specify a file name, FDT uses the current frame file 
name by default. 


e The default file type for the report file is .RPT. 


5.4.12 SAVE 


The SAVE command saves the current file on disk and displays a 
confirmation message. If the file already exists, it is assigned the 
next higher version number. 


Formats: 


SAVE 


5.5 FRAME COMMANDS 


Frame commands, allow you to change and save frames. They can be 
typed in response to the prompt: 


Frame Command: 


With the exception of the QUIT command, you can abbreviate any frame 
command to a single character. 


If you enter a command and omit required parameters, FDT displays 
prompts requesting them. 


FRAME COMMANDS 


5.5.1 ACTION 


The ACTION command invokes Action forms for the options on the current 
menu. An Action form specifies a keyword, help frame pointer, and 
(single-choice menus only) action string for each option. 


Format : 
ACTION 

ALL specifies all options in the current menu. This is’ the 
default. 

NEW specifies only those options for which you have not yet 


entered an action form. 
option specifies a particular option by ordinal number (1 to 12). 


Notes: 


@® Action information can be assigned only to menus (not text 
frames). 


@® Each option must be assigned action information. 
e If you specify an option that has already been assigned action 
information, the current description is displayed on the Action 


form. You can then enter new information or change existing 
information. 


5.5.2 DISPLAY 

The DISPLAY command invokes a Display form for the current frame. The 
Display form contains fields that correspond to the fields in the 
frame. 


Format: 


DISPLAY 


FRAME COMMANDS 


Notes: 


@ A Display form for a menu contains the title, explanatory text, 
options, and prompt. 


@ A Display form for a help text frame contains the title and text. 


e A Display form for a message frame contains the message text. 


5.5.3 EXIT 

The EXIT command saves the current frame on disk in the current file, 
displays a confirmation message, and returns control to file editing 
level. 


Format: 


EXIT 


CAUTION 
This command saves the current frame, not the _ file. 
To save the file, enter an EXIT or SAVE command at 
file command level when you are finished editing. 


Otherwise all the changes made in this session will be 
discarded. 


5.5.4 HELP 
The HELP command displays a list of FDT frame commands. 
Format : 
HELP 
Notes: 


e If you type HELP to the Frame Command prompt while you are working 
on a text or message frame, the ACTION command will not be listed. 


FRAME COMMANDS 


5.5.5 PROFILE 


The PROFILE command displays a Profile form for the current’ frame. 
The Profile form contains data that describes the purpose and 
operation of the frame to menu services and to your application. This 
information is not visible to the user. 


Formats: 
PROFILE 
Notes: 
e The Profile form for a single-choice menu contains a 


self-documenting description, a global help frame pointer, the 
default option, and the global action string. 


@e The Profile form for a help menu contains a_e self-documenting 
description, a previous help frame pointer, and the default 
option. 

@® The Profile form for a help text frame contains a self-documenting 
description, the frame's screen location, a previous help frame 
pointer, and a next help frame pointer. 


® The Profile form for a message frame contains a self-documenting 
description. 


The QUIT command returns control to file editing command level without 
saving the current frame. Any changes made to the frame are 
discarded. 
Formats: 

QUIT 


Notes: 


@® All of the characters in the QUIT command must be typed. 


5.5./ SAVE 


The SAVE command saves the current frame on disk in the current file, 


ee 


FRAME COMMANDS 


displays a confirmation message, and returns control to file editing 
level. 


Format: 


SAVE 


CAUTION 


This command saves the current frame, not the file. 
To save the file, enter an EXIT or SAVE command at 
file command ltevel when you are finished editing. 
Otherwise all the changes made in this session will be 
discarded. 


5-6 PROFILE, DISPLAY, AND ACTION FORMS 


FDT provides access to frame descriptions by means of forms. When you 
enter the ADD command to create a new frame, FDT displays a series of 
forms for you to fill in. When you enter the MODIFY command to edit 
an existing frame, FDT allows you to specify which forms you want to 
modify. 


As shown in Figure 5-1, there are three types of forms: 
@® The Profile Form 
The Profile form (invoked by the PROFILE command) contains data 


that describes the purpose and operation of the frame to POSRES 
and to your task. This information is not visible to the user. 


@® The Display Form 
The Display form (invoked by the DISPLAY command) contains fields 
that correspond to the fields in the frame. It describes how the 
form will appear to the user. 

@® The Action Form 
An Action form (invoked by the ACTION command) is for menu frames 


only. It specifies a keyword, help frame pointer, and 
(single-choice menus only) an action string for each option. 


PROFILE, DISPLAY, AND ACTION FORMS 


Profile for Single Choice Menu MAIN 


Frame Description 
This is the main menu for the elementary education application. 


Global Help Frame [(MENU} 
Default Option [3 } 


Global Action String 


Display for Single Choice Menu MAIN 


C ELEMENTARY ED'CATION APPLICATION 


This application offers elementary education in seven fieids of study. 
one of the courses listed here. 


BIOLOGY 

COMPUTER SCLENCE 
GEOGRAPHY 
GOVERNMENT 
HiSTCRY 
LITERATURE 
MATHEMAT (CS 


({ Make a selection and press the DO key: 7 


Aczion Number 3 for Single Choice Menu MAIN 


vescription: GEOGRAPHY 


Action Descriction 


[ This is the description of the Geography option. 


Option Xeyword [SEC 
Cption Yelp Frame CHELPGEO ] 


Oprion Action String 


MENU DEFINITION FILE 


FRAME 4 
FRAME 5 
FRAME 6 


FRAME 3 
FRAME 7 


Ww 
= 
< 
or 
ue 


FRAME 8 
FRAME 9 
FRAME 10 
FRAME 11 


MENU 


ELEMENTARY EDUCATION APPLICATION 


This application offers elementary education in seven fields of study. Select 
one of the courses Listed here: 


BIOLOGY 

COMPUTER SCIENCE 
GEOGRAPHY 
GOVERNMENT 
HISTORY 
LITERATURE 
MATHEMATICS 


Additional Options available 


Make a selection and press the DO key: 


Figure 5-l: Forms for a Single-Choice Menu 
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PROFILE, DISPLAY, AND ACTION FORMS 


Each form contains’ one or more fields. Some fields are 
self-explanatory, such as comment fields which are essentially self- 
documentation. Other fields are more complex and interrelated, such 
as help frame pointers. 


Some fields are optional; others are required. If you fail to fill in 
a required field, FDT accepts the frame. However, when you try to 
convert the frame definition file to executable format, an error 
occurs and the conversion fails. 


You can use your keyboard’s numeric keypad and arrow keys’ to 
manipulate text within a field. Figure 5-2 shows the layout of the 
numeric keypad. Like other screen editors, FDT uses "insert mode" for 
entering text. There is no “insert" command. To enter text, simply 
type on the main keyboard. 


The keypad keys operate as follows: 


| DELETE 
CURRENT 
LINE 


DELETE 
| | woRD 


DELETE 
CHAR 


Figure 5-2: FDT Screen Editor Keypad 


5-14 


PROFILE, DISPLAY, AND ACTION FORMS 


Move the cursor forward, backward, up, or down within 
and between fields. You can use the 6, 4, 8, and 2 keys 
(respectively) on the numeric keypad for the same 
purpose. 


Displays a description of the field the cursor 
currently points to. If pressed again, displays a 
description of the keypad keys. 


Deletes from the cursor to the end of the line. 


Deletes from the cursor to the next word. 
Deletes the character the cursor is on. 


Positions the cursor at the beginning of the next field 
on the form. 


Positions the cursor at the beginning of the previous 
field on the form. 


Returns control to frame editing command level unless 
you are filling in multiple Action forms, in which case 
the next Action form for the menu (if there is one) is 
displayed. 


CREATING A SINGLE-CHOICE MENU 


5./ CREATING A SINGLE-CHOICE MENU 


5.7.1 The Profile Form 


Profile for Single Choice Menu [IDENTIFIER] 


Frame Description 


Global Help Frame [ 7} 
Default Option[ Jj 


Global Action String 


Figure 5-3: Profile Form for Single-Choice Menu 


Frame Optional Six lines of Enter a description of the 
Descrip- 72 charac- overall purpose and operation of 
tion ters | the menu. For example, you can 
document the content and meaning 
of the global action string. 


Specify the help frame to be 
displayed when the selector is at 
| the rest position or 1f no option 
| frame pointer exists. 


Global 
Help 
Frame 


Eight alpha- 
numeric 
characters 


Optional 


| Specify the ordinal number of the 
option on which the selector is 
to begin when the menu is 
displayed. Tf you leave this 
field blank, the selector begins 

at the rest position. 


Default Two digits 


option 


Optional 


Specify a string that associates 
some useful data with this menu. 
When the MFRAME routine’ reads 
this menu into memory, it returns 
i the global action string to your 
| task, which can use or ignore it. 


72 charac- 
ters 


Global 
action 
string 


Optional 


CREATING A SINGLE-CHOICE MENU 


5.7.2 The Display Form 


Display for Single Choice Menu [IDENTIFIER] 


TITLE. ‘TEXT 


EXPLANATORY TEXT 


OPTION DESCRIPTION 


C 


PROMPT 


Figure 5-4: Display Form for Single-Choice Menu 


Explana- 
tory 
text 


Option 
descrip- 
tions 


Prompt 


Required 


Optional 


Required 


Required 


64 alphanu- 
meric char- 
acters 


Three lines 
of 72 char- 
acters 


Twelve lines 
of 64 char- 
acters 


72 charac- 
ters 


2 awe ae 


Enter the title to be displayed 
on the first line of the menu. 


Enter text introducing the user 
to the options listed on this 
menu. 


'Enter the option list. You must 


specify at least one option. 


Enter a string that requests’ the 
user to make a selection. 


CREATING A SINGLE-CHOICE MENU 


5.7.3 The Action Form 


Action Number [#1 for Single Choice Menu [IDENTIFIER] 


Description: {OPTION DESCRIPTION] 


Action Description 


Option Keyword [ 
Option Help Frame [ J 


Option Action String 


Figure 5-5: Action Form for Single-Choice Menu 


The message line at the top of the form shows the ordinal number of 
the option for which action is being assigned. It also shows the 
identifier of the menu on which the option is displayed. 


| Optional |Two lines of | Enter a description of the 

| | 72 charac-— overall purpose and operation of 

ters the option. For example, you can 
document the content and meaning 
of the option action string. 


Type 


Action 
Descrip- 
tion 


30 charac- Enter any contiguous substring of 
ters the option. This keyword appears 
|! in bold when the menu is 
displayed in order to indicate 
which characters the user can 

type to select this option. 


Option | Required 


keyword 


Eight alpha- Specify the help frame to _ be 

numeric displayed when the user presses 

characters the HELP key while the selector 
| is positioned at this option. 


Option Optional 
Help 


Frame 


72 charac- Specify a string that associates 
| ters | some useful data with this 
option. When the user selects) an 
option, the MENU routine returns 
this string to your task, which 
can use or ignore it. 


Option Optional 
action 


string 
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5.8 CREATING A HELP MENU 


5.8.1 The Profile Form 


Profile for Help Menu [IDENTIFIER] 


Frame Description 


Previous Help Frame [ 
Default Option [ ‘| 


Figure 5-6: Profile Form for Help Menu 


Frame Optional Six lines of Enter a description of the 
Descrip- 72 charac- overall purpose and operation of 
tion ters the menu. For example, you can 


document how it fits into the 
larger help structure. 


Previous Optional Eight alpha- Specify the help frame to be 
Help numeric displayed when the user presses 
Frame characters the PREV SCREEN key. 


Default Optional Two digits Specify the ordinal number of the 

option option on which the selector is 
to begin when the menu is 
displayed. If you leave this 
field blank, the selector begins 
at the rest position. 


CREATING A HELP 


5.8.2 The Display Form 


Display for Help Menu [IDENTIFIER] 
TITLE. TEXT: 


EXPLANATORY TEXT 


OPTION DESCRIPTION 


MENU 


[ PROMPT 


Figure 5-7: Display Form for Help Menu 


Required 64 alphanu- 
meric char- 


acters 


Three lines 
of 72 char- 
| acters 


Explana- 
tory 
text 


Optional 


Twelve lines 
of 64 char- 
' acters 


Option | Required 
descrip- 


tions 


72 characy 
ters 


Prompt Required 


Enter the title to be displayed 
on the first line of the menu. 


Enter text introducing the user 
to the options listed on this 
menu. 


Enter the option list. You must 


specify at least one option. 


Enter a string that requests’ the 
user to make a selection. 


CREATING A HELP MENU 


5.8.3 The Action Form 


Action Number [#] for Help Menu [IDENTIFIER] 


Description: [OPTION DESCRIPTION] : 


Action Description 


Option Keyword [ 
Option Help Frame [ 


Figure 5-8: Action Form for Help Menu 


Action Optional Two lines of Enter a description of the 

Descrip- 72 charac- | overall purpose and operation of 

tion ters the option. For example, you’ can 
document whether the option help 
frame is a menu or a text frame. 


Option Required 30 charac- Enter any contiguous substring of 

keyword ters the option. This keyword appears 
in bold when the menu is 
displayed in order to indicate 
which characters the user can 
type to select this option. 


Required Eight alpha- Specify the name of the help menu 
numeric or text frame to be displayed 
characters when the user selects this 

option. 


CREATING A HELP TEXT FRAME 
5.9 CREATING A HELP TEXT FRAME 


5.9.1 The Profile Form 


Profile for Help Text [IDENTIFIER} 


Frame Description 


Frame Location [FULL] 
Previous Help Frame 
Next Help Frame [ 


Figure 5-9: Profile Form for Help Text Frame 


Frame Optional 
Descrip- 
tion 


Six lines of 
72 charac- 
ters 


Enter a description of 
overall content of the frame. 


Frame 
Location 


Required Specific 


options 


Specify "PULL ys “TOP 3 or 
"BOTTOM", according to where you 
want this frame to appear. A full 
frame has 16 lines of text; a top 
or bottom frame has eight lines. 
The default is "FULL". To change 
it, position the cursor on_ the 
"FEF" and press the DELETE WORD key 
on the keypad. 


| Previous 
Help 
Frame 


Optional Eight alpha- 
numeric 


characters 


Specify the help frame to be 
displayed when the user presses 
the PREV SCREEN key. 


Next 
Help 
Frame 


Optional Eight alpha- 
numeric 


characters 


Specify the help frame to. be 
displayed when the user presses 
the NEXT SCREEN Key. 


CREATING A HELP TEXT FRAME 


5.9.2 The Display Form 


Display for Help Text ( IDENTIFIER] 


Help Text 


Figure 5-10: Display Form for Help Text Frame 


Full screen and top or bottom half help text frames have different 
Display forms representing the difference in the number of lines in 


the frame. However, they all share the same fields, and the _ full 
screen help text frame is representative. 


Required 64 alphanu- 
meric char- 


acters 


Enter the title to be displayed 
on the first line of the frame. 


Required 16 lines of 
72 charac 


ters 


Enter at least one line of text 
that provides help on some aspect 
of your application. 


CREATING A MESSAGE TEXT FRAME 


5.10 CREATING A MESSAGE TEXT FRAME 


5.10.1 The Profile Form 


Profile for Message [IDENTIFIER] 


Frame Description 


Figure 5-ll: Profile Form for Message Frame 


Frame 
descrip- 
tion 


17 lines of 
72 charac- 
ters 


Optional Enter text that documents” the 
contents and purpose of the 


message. 


5.10.2 The Display Form 


Message text frames are displayed with no border or _ prompt. The 
Display form for this type of frame is simply a blank screen with the 
usual message line at the top identifying the current frame. 


Message Required 21 lines of Enter the message text. You must 


text 79 charac- enter at least one line. 
ters 


5.11 RESOLVING ERRORS 


All user errors occurring with FDT produce a short beep from the 
keyboard. 


RESOLVING ERRORS 


While you are filling in forms, if you press a key that is not on the 
FDT keypad or attempt to type over field boundaries, the keyboard 
beeps and the key action is ignored. 


All other user errors produce a descriptive error messsage following 
the keyboard beep. FDT Error messages are described in Appendix B. 


Certain invalid keystrokes disrupt the FDT screen display. For 
example, a line feed entered while an FDT form is displayed scrolls 
the screen upward. Also, a backspace typed to the File or Frame 
Command prompt allows typing over the prompt, causing valid commands 
typed at this point to be rejected. If you enter an invalid keystroke 
that alters a form display, type CTRL/W to refresh the screen and 
continue. If you enter an invalid keystroke that alters a File or 
Frame Command prompt, enter valid commands until one is accepted. 


5.12 SAMPLE TERMINAL SESSION 

The following is a sample of a terminal session using the Frame 
Development Tool on an RSX-11M/M-PLUS system. It is recommended that 
you use the single-choice menu shown in Figure 5-1 to fill in the 
forms. 


S RUN $FDT 


FDT starts and prompts for a file name. In this example, FDT creates 
a new file. 


Filename: SAMPLE 
FDT prompts for the type of frames to be stored in the file. 
Create (H)elp, (M)essage, or (S)ingle-choice menu file? S 


The file SAMPLE.DAT will contain single-choice menus. FDT prompts for 
a file command. 


File Command: ADD MAIN 
The ADD command creates a new frame called MAIN. Because it iS a new 
frame, FDT displays a Profile form. When you finish the form, press 
the ENTER key. MAIN is now the current frame. FDT prompts for a 
frame command. 


Frame Command: DISPLAY 


The DISPLAY command creates a Display form for MAIN. When you finish 
the form, press the ENTER key. FDT prompts for another frame command. 


SAMPLE TERMINAL SESSION 


Frame Command: ACT TON 
fale, & g ‘ aa 
e Be he de et 


The ACTION command creates Action forms for each option on the display 
form for MAIN. When you finish an Action form, press the ENTER key. 
When all the Action forms are done, FDT prompts for another’ frame 
command. Suppose that you want to correct a mistake on the Action 
form for the third option. 


Frame Command: ACTION 3 


FDT displays the action form for option three with the information you 
entered before. When you finish the form, press the ENTER key. FDT 
prompts for another frame command. 


Frame Command: SAV& 


MAIN is saved on disk, and a confirming message is displayed. FDT 
prompts for a file command. 


File Command: SAV& 


FDT saves the file SAMPLE.DAT, which contains MAIN, on disk = and 
returns control to host system command level. 


Suppose that you decide to modify the Profile form for MAIN. 


amr 
ye Pied 


és 4 


es 


e 
Filename: 
e 


FDT extracts MAIN, displays a message confirming that MAIN is 
available for modification, and prompts for a frame command. 


Frame Command: PR 


The PROFILE command invokes the Profile form for MAIN, the current 
frame. The information you entered before is still there. When you 
finish the form, press the ENTER Key. FDT prompts for a frame 
command. 


ES 


Frame Command: SAVE 


f 


FDT saves MAIN with the new Profile form and prompts for ae file 
command. 


File Command: QUIT 
FDT discards all changes made to the file SAMPLE.DAT (including the 


new Profile form) and returns control to host system command level. 
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CHAPTER 6 


INSTALLATION COMMAND LANGUAGE 


The application installation (.INS) file identifies all the files’ and 
task images that make up an application. You must create separate 
-INS files for P/OS Hard Disk and P/OS Diskette. If your application 
will run on both systems, you must write two .INS files. 


The .INS file is used by the following programs: 


@ The Application Diskette Builder uses the .INS file to identify 
the files and task images to copy to the application diskette(s). 


@e P/OS Disk/Diskette Services install service uses the .INS file to 
identify the files to copy to the disk at installation time. 


@® P/OS Diskette Prepare Application uses the .INS file to determine 


which files to copy from the P/OS Library diskettes onto the 
application diskette. 


@® The PRO/Dispatcher uses the .INS file at run time to identify task 
images (it adds the names to its list of executable tasks), to 
open any Menu and Help definition files (specified in ASSIGN 
statements), and to start the first application task. 


@e P/OS Disk/Diskette Services remove service uses the .INS file to 
identify the files to delete from the disk at application removal. 


6.1 INSTALLATION COMMAND FILE FORMAT 


An installation command (.INS) file is an ordinary text file that you 
can create with any editor. Some Tool Kit languages provide a 
facility for creating a general-purpose .INS file. 


INSTALLATION COMMAND FILE FORMAT 


The format of an .INS file is shown in Figure 6-1. Command lines can 
be up to 132 characters long and can have one command per line. The 
commands muSt appear in the order shown (with exceptions described 
under individual commands). Mandatory commands are shown in bold. 


NAME "name" 

FILE filename/option 
Loe MOUNT volume 

FILE filename/option 


2 EXECUTE taskspec/option 
3 REQUIRE filename 
3 OPTIONS xxx 
3 LOAD Xxx 
INSTALL filename/option 
ASSIGN MENU filename 
ASSIGN HELP filename frameid 
ASSIGN LOGICAL name “equiv" 
RUN taskname 
1 Required for multiple-diskette applications (see Section 6.10) 
2 P/OS Hard Disk only (see individual commands by name) 
3 P/OS Diskette only (see individual commands by name) 


Figure 6-l: Installation Command File Format 


The order of the INSTALL commands determines the order in which task 
image files are processed when an application is started. The order 
of the FILE commands determines the order in which files are copied 
from the application diskettes to the hard disk. 


To minimize the disk seek time and enhance the application startup 
process, follow these guidelines when creating an .INS file: 


@ Place FILE commands corresponding to INSTALL commands before any 
other FILE commands and arrange them in the same order as the 
INSTALL commands. (INSTALL commands with the /COMMON and /LIBRARY 
options must appear before INSTALL commands with the /TASK 
option.) 


@e Wherever possible, group FILE commands by directory. This will 
minimize seek time in retrieving directory information. 


Subsequent sections provide descriptions of the individual commands 
and list the required commands for P/OS Hard Disk and P/OS Diskette 
applications. 


ASSIGN HELP 


6.2 ASSIGN HELP 
This command assigns a default help file to your application and can 
be used in place of the Open Help File service routine at run time. 
It assumes that the specified help file is placed in APPLSDIR at 
installation. 
Format: 

ASSIGN HELP filename frameid 
filename is a string of up to 13 characters that specifies the name 


and type of a help definition file. 


frameid is a string of up to eight characters that specifies’ the 
default help frame. 


Notes: 
@® The ASSIGN HELP command is optional. 


@® You can have only one ASSIGN HELP command per .INS file. 


6.3 ASSIGN LOGICAL 


This command defines a logical name at run time. (See the Tool Kit 
User's Guide for information about logical names.) 


Format: 
ASSIGN LOGICAL name “equiv” 
name is a string that specifies the logical name that is to be 
defined. 
equiv is a string that specifies the equivalence name. 
Notes: 
@® The ASSIGN LOGICAL command is optional. 


@® Multiple ASSIGN LOGICAL commands can be used. 


ASSIGN MENU 


6.4 ASSIGN MENU 
This command assigns a default menu file to your application and _ can 
be used in place of the Open Menu File service routine at run time. 
It assumes that the specified menu file is placed in APPLSDIR at 
installation. 
Format : 

ASSIGN MENU filename 
Filename is a string of up to 13 characters that specifies the name 

and type of a help definition file. 

Notes: 


@® The ASSIGN MENU command is optional. 


@ You can have only one ASSIGN MENU command per .INS file. 


6.5 COMMENT (!) 


An exclamation point (!) indicates that the rest of the line is a 
comment. Comment lines can appear anywhere in the .INS file. 


Formats: 


! descriptive text 


6.6 EXECUTE (P/OS HARD DISK ONLY) 


This command causes a specified task to execute at application install 
time or remove time (depending on the option selected). If the task 
exits with status greater than one, the installation or _ removal 
aborts. 


The instllation command (.INS) file executes sequentially, thus’ the 
position of the EXECUTE command relative to FILE commands is 
signicant, as explained below. 


EXECUTE (P/OS HARD DISK ONLY) 


Formats: 
EXECUTE taskspec/option 
taskspec the directory, file name, and file type of the task image to 


be executed. You can use the logical name "APPLSDST:" which 
equates to the application directory (see notes). 


option is one of the following options: 

/JINS executes the specified task at application 
installation. This command must follow the FILE 
command that copies the specified task image to the 
hard disk. It can precede any other FILE command in 


order to avoid copying files needlessly on aborted 
installations. 


/REM executes the specified task at application removal. 
This command must precede any FILE/DELETE commands so 
that if the removal aborts, no files will have been 
deleted. 
Notes: 


@® The EXECUTE command is supported for P/OS Hard Disk only. 


@® You can place an EXECUTE command anywhere that a MOUNT or FILE 
command can be placed. 


® The logical name APPLSDST serves the same purpose that APPLSDIR 
performs at run time: it equates to your application's directory. 


At installation or removal time, however, APPLSDIR is not defined 
(for your application). 


6.7 FILE 
This command specifies the name of an application file. You must 
supply a FILE command for each file to be copied at application 
installation time (or deleted at removal time). 
Format: 

FILE filename/option 


filename is a string of up to 13 characters that specifies the name 
and type of an application file. 


option 


Notes: 


FILE 


must be one of the following strings (there is no default): 


KEEP prevents the file (and the application directory) 
from being deleted when the application is removed. 


DELETE allows the file (and the application directory if 
there are no files remaining) to be deleted when the 
application is removed. 


@® You must supply at least one FILE command per .INS file. 


@ Do not include a FILE command for the .INS file itself. 


6.8 INSTALL 


This command specifies each task image or library to be installed 
(placed in the installed task list) at run time. 


Formats 


filename 


option 


NOREMOVE 


INSTALL filename/option/NOREMOVE 


is a string that specifies the name and type of a file to be 
installed. You also can specify a directory name. 


must be one of the following strings: 


LIBRARY specifies that the file is a read-only resident 


library. 

COMMON specifies that the file is a read/write resident 
library. 

TASK specifies that the file is an executable task 
image. 


applies to INSTALL/TASK commands only. It specifies that 
the task will not be aborted or removed if the application 
exits or is aborted. 


INSTALL 


Notes: 


@® You must supply at least one INSTALL command per .INS file. 


@e All INSTALL commands with /LIBRARY and /COMMON options must 
precede any INSTALL command with a /TASK option. 


@® The /NOREMOVE option can be used to ensure that a non-interactive 


"background" task, such as a file transfer, is not aborted 
inadvertantly. 


Use care with the /NOREMOVE option. If the name of the task is 
duplicated by another application, the second task of that name 
cannot be installed until the first is removed. 


Also, once you install a task with /NOREMOVE, it remains installed 
(it can be checkpointed if active) until another task explictly 
removes it (the PRO/Tool Kit DCL REMOVE command, for example), or 
until the system is powered down. 


For more information about installing tasks, refer to the PROTSK 
routine in the P/OS System Reference Manual. 


@® For P/OS Diskette, you must supply an INSTALL command for each 


task image or library listed in a REQUIRE command. (See Section 
6.16 for details.) 


6.9 LOAD (P/OS DISKETTE ONLY) 
This command loads a device driver required for the application to 
run. The device driver is unloaded when the application exits. (See 
Section 6.16 for details.) 
Format : 
LOAD driver 
driver is a string that specifies the physical name of the device 
driver to be loaded. 


Notes: 


@® You must supply a LOAD command for each device driver required 
during application execution. 


LOAD (P/OS DISKETTE ONLY) 


@ P/OS Diskette V1.7 includes a configuration diskette, from which 
the end user can load the XK (PRO/Communications) and TMS drivers 
into memory. This is a user option only. Do not assume the 
driver will be loaded on an end user's” system. If your 
application runs on P/OS Diskette and requires either of these 
drivers, include the appropriate LOAD commands in the .INS file. 


6.10 MOUNT (P/OS HARD DISK ONLY) 

This command specifies the names of the volumes that make up = an 
application that is distributed on more than one diskette. At 
installation time, the MOUNT command specifies when the user must 
insert a new application diskette for installation to continue. The 


Application Diskette Builder copies the files named in subsequent FILE 
commands to the specified volume. 


Format 
MOUNT volume 

volume is a string of up to 12 characters that specifies a volume 
name (no colon). 

Notes: 


@e The MOUNT command is optional for applications that reside 
entirely on one diskette. 


e@ No MOUNT command is required for the first diskette of a multiple- 
diskette application. 


6.11 NAME 
This command specifies the application name seen by the end user when 
the application is installed. P/OS Hard Disk Install places this name 
(or one supplied by the end user) on a menu. 
Format: 

NAME “name” 


name is a string of up to 40 characters that identifies your 
application. 


NAME 


Notes: 


@® You must supply exactly one NAME command per .INS file. 


® You can use single or double quotes to delimit the string. 


6.12 OPTIONS (P/OS DISKETTE ONLY) 

This command specifies an optional system feature that must be present 
on the target system for the application to run. (See Section 6.16 
for details.) 


Formate 


OPTIONS feature 


feature specifies the system feature to be included. 
Notes: 
® The only feature currently supported by the OPTIONS command is 
GRAPHICS. You must specify GRAPHICS for applications that use the 


CORE Graphics Library or PRO/GIDIS. Future versions of the Tool 
Kit and P/OS may support other options. 


6.13 REQUIRE (P/OS DISKETTE ONLY) 
This command specifies which system files and libraries are to _ be 
copied from the system library diskettes to the application diskette 
by the Prepare Application utility. 
Format: 

REQUIRE filespec 


filespec is a string that specifies a system directory followed by a 
file name and type. 


6.14 RUN 


This command specifies the name of the first task to execute at = run 


6=9 


RUN 


time. 
Format: 
RUN taskname 
taskname is a string of up to six characters that specifies the name 
of a task. 
Notes: 
@® Include one RUN command per .INS file. 
@ The task name must be identical to the name specified in the TASK 
option (if present) in your PAB command file. If you don't use a 


TASK option, the task name is the first six characters of the name 
of the task image file on disk. 


6.15 REQUIRED COMMANDS FOR P/OS HARD DISK APPLICATIONS 


If application uses: Installation file must include: 

BASIC-PLUS-2. ~—~—~—sOINSTALL [2ZSYS] PBFSML.TSK/LIBRARY 
COBOL-81 INSTALL [ZZSYS]C81LIB.TSK/LIBRARY 
DIBOL INSTALL [ZZSYS] DBLRES.TSK/LIBRARY 
FORTRAN-77 INSTALL [ZZSYS] PROF77.TSK/LIBRARY 
PASCAL INSTALL [ZZSYS] PASRES.TSK/LIBRARY 
Callable editor (CET) INSTALL [ZZSYS] PASRES.TSK/LIBRARY 


INSTALL [Z2ZSYS] CET.TSK/TASK 


PRO/SORT INSTALL [ZZSYS] PASRES .TSK/LIBRARY 
INSTALL [Z2ZSYS] PROSORT.TSK/TASK 


NOTE 
P/OS Hard Disk applications do not need FILE or 


INSTALL commands for PRO/FMS-11, PRO/GIDIS, POSRES, 
PRO/Communications, RMSRES, or the print utility. 


REQUIRED COMMANDS FOR P/OS DISKETTE APPLICATIONS 


6.16 


If application uses: 


(All .INS files) 


BASIC=PLUS=2 


Callable editor (CET) 


COBOL-81 


(debugging on diskette) 


COMLIB 


DIBOL 


FMS 


FORTRAN- 77 


CORE Graphics Library 


PRO/GIDIS 


HP Plotter 


OLDFIL/NEWFIL 


REQUIRED COMMANDS FOR P/OS DISKETTE APPLICATIONS 


Installation file must include: 


REQUIRE 
REQUIRE 
REQUIRE 


REQUIRE 
REQUIRE 
INSTALL 


REQUIRE 
REQUIRE 
REQUIRE 
REQUIRE 
REQUIRE 
INSTALL 
INSTALL 


REQUIRE 
REQUIRE 
REQUIRE 
INSTALL 


REQUIRE 
REQUIRE 
REQUIRE 
INSTALL 
REQUIRE 
REQUIRE 
REQUIRE 
INSTALL 


REQUIRE 
REQUIRE 


OPTIONS 


INSTALL 
INSTALL 


REQUIRE 
OPTIONS 
INSTALL 


REQUIRE 
INSTALL 


REQUIRE 


[ZZSYS] CMAIN.TSK 
[ZZSYS] CTEX.MSG 
[ZZSYS] POSRES.TSK 


[001002] BASIC2.ERR 
[ZZSYS] PBFSML.TSK 
[ZZSYS] PBFSML.TSK/LIBRARY 


[ZZSYS] CET.TSK 

[ZZSYS] PASRES.TSK 

[ZZSYS] PROSE.HLP 

[ZZSYS] PROSE.MSG 

[ZZSYS] PROSE.UDK 

[ZZSYS] PASRES.TSK/LIBRARY 
[ZZSYS] CET. TSK/TASK 


[ZZSYS]C81LIB.TSK 
[001002]C81RTE.TXT 
{[001002]C81DBG.HLP 
[ZZSYS]C81LIB.TSK/LIBRARY 


[zZSYS] COMLIB.TSK 


[001002] DIBOLERR.MSG 
[zZZSYS] DBLRES.TSK 
[ZZSYS] DBLRES.TSK/LIBRARY 


[001002] FMSERR.MSG 


[001002] PROF77.MSG 
[ZZSYS] PROF77.TSK 
[ZZSYS] PROF77.TSK/LIBRARY 


[zZ2SYS]GDSCOM.TSK 

[ZZSYS] CGLFPU.TSK 
GRAPHICS 
[ZzZSYS] GDSCOM. TSK/LIBRARY 
[ZZSYS] CGLFPU.TSK/LIBRARY 


[ZZSYS] GDSCOM.TSK 
GRAPHICS 
[ZZSYS]GDSCOM.TSK/LIBRARY 


[ZZSYS]GIHPGL.TSK 
[zZZSYS] GIHPGL.TSK/TASK 


[zZzZSYS] SYSTEM.MNU 
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REQUIRED COMMANDS FOR P/OS DISKETTE APPLICATIONS 


PASCAL 


Print services 


PRODIR (POSSUM) 


PROFBI (POSSUM) 


PRO/SORT 


TMS 


XK Driver 


REQUIRE 
REQUIRE 
INSTALL 


REQUIRE 
REQUIRE 
INSTALL 


REQUIRE 
REQUIRE 
REQUIRE 
REQUIRE 
REQUIRE 
INSTALL 
INSTALL 


REQUIRE 


LOAD XT: 


[001002] PASERR.MSG 
[ZZSYS] PASRES.TSK 
[ZZSYS] PASRES.TSK/LIBRARY 


[ZZSYS]CPRNT.TSK 
[2ZZSYS] PRINT.MSG 
[ZZSYS] CPRNT.TSK/TASK 


[ZZSYS] CREDEL.TSK 

[ZZSYS] SUMFBI.TSK 

[ZZSYS] PROSORT.SYS 
[ZZ2SYS] PROSORT.TSK 
[ZZSYS] PASRES.TSK 

[ZZSYS] PASRES.TSK/LIBRARY 
[ZZSYS] PROSORT.TSK/TASK 


[ZZSYS] XTDRV.TSK 


REQUIRE [ZZSYS] XKDRV.TSK 


LOAD XK: 


INSTALL 


[ZZSYS] COMLIB.TSK/LIBRARY 


CHAPTER 7 


MACRO-11 ASSEMBLER (PMA) 


Professional Tool Kit MACRO-11 (PMA) is the PDP-ll relocatable 


assembly language processor. Refer to the PDP-11 MACRO-11 Language 
Reference Manual for detailed information about PMA. 


7.1 INVOKING PMA ON THE PRO/TOOL KIT 


To invoke PMA on a Professional running the PRO/Tool Kit, type: 


S RUN SYSSSYSTEM:MAC 
OF 
$ RUN SMAC 


7.2 INVOKING PMA ON RSX-11M/M-PLUS (DCL) 
If PMA is installed on your system as "...PMA", type: 


S$ PMA command 


where "command" is a command string in the general format 
"output=input" as described in the MACRO-11 documentation. 


If PMA is not an installed task, type: 


S IN S$PMA 


and specify a file name when FDT prompts. 


7.3 INVOKING PMA ON VAX/VMS 


For convenience, edit your LOGIN.COM file and insert the following 


Wat 


INVOKING PMA ON VAX/VMS 


symbol definition: 
$ PMA :== SPMA 

Once the symbol is defined, you can invoke PMA by typing: 
$ PMA command 


where "command" 1S a command string in the general format 
"Output=input" as described in the MACRO-11 documentation. 


CHAPTER 8 


POSRES USER INTERFACE LIBRARY ROUTINES 


This section describes the routines provided by POSRES, the P/OS User 
Interface Library. 


8.1 NOTES ON USING POSRES ROUTINES 


® You can call POSRES routines from MACRO-11 or from high-level 
languages. POSRES uses the PDP-11 calling sequence convention, 
which is described in the Tool Kit User's Guide. POSRES preserves 
the stack pointer (SP); it does not preserve any other registers. 


@e Tasks that use POSRES must include some specific information in 
their PAB files, as described in the Tool Kit User's Guide. 


@ All POSRES routines accept a two-word integer parameter named 
"Status". The values returned in the status block vary according 
to the routine called and are listed in Appendix C. 


@ Some POSRES routine parameters specify values (input parameters), 
Others return values (output parameters), and some _ do both. 
Output parameters must be variables. Input parameters, however, 
can be variables, constants, or constant expressions, depending on 
your language. If it does not support constant expressions as 
actual parameters, read "expression" as "constant." 


@e Several POSRES routines accept parameters consisting of variable- 
length character (byte) string buffers. All string buffers are 
accompanied by an integer value that specifies the length of the 
buffer. Because these values mean the same thing, they are all 
named "buflen" and directly follow the buffer parameter. 


® String buffers that return values are accompanied by an extra 
parameter that returns an integer value representing the actual 
length of the string returned in the buffer. Because these 
integer variables all mean the same thing, they are all named 
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NOTES ON USING POSRES ROUTINES 


"strlen" and directly follow the “buflen" parameter. 


Some POSRES routines have parameters that can can be omitted from 
the right. For example, if the fourth parameter is omitted, then 
parameters five, six, and seven must also be omitted. 


Some POSRES routines have parameter groups with a variable format 
within the group. Short parameter lists (no more than three or 
four groups) are easier to read and debug. Long parameter lists, 
however, are more efficient because they require fewer calls. 


POSRES parameter list run-time checking is somewhat’ limited. 
Check your source code against the lists in this’ chapter 
carefully. Invalid parameters can cause unpredictable results. 


CLOSE HELP FILE (HCLOSE) 


8.2 CLOSE HELP FILE (HCLOSE) 

This routine closes the current help definition file. 

Format: 
HCLOSE (status) 

status is a two-word integer array that returns a code indicating the 
results of the routine call (see Appendix C). 

Example: 


1990 REM *** Closing help definition file *** 
2000 CALL Hclose BY REF( Stblk%() ) 


8.3 CLOSE MENU FILE (MCLOSE) 

This routine closes the current menu file. 

Format s 
MCLOSE (status) 

status is a two-word integer array that returns a code indicating the 
results of the routine call (see Appendix C). 

Example: 


2020 REM *** Closing menu definition file *** 
2030 CALL Mclose BY REF( Stblk3%() ) 


DISPLAY DYNAMIC MENU (DMENU) 


8.4 DISPLAY DYNAMIC MENU (DMENU) 


This routine displays the single-choice menu in the dynamic buffer. 


Formats: 


status 


action 


buflen 
strlen 
display 


add opt 


msgl 


buflen 


msg2 


buflen 


Notes: 


DMENU (status, action, buflen, strlen, display, add opt, 


msgl, buflen, msg2, buflen) 
1S a two-word integer array that returns a code indicating 
the results of the routine call (see Appendix C). 
is a string buffer of up to 80 characters that returns’ the 
action string associated with the option selected. The 
action string is truncated or filled with blanks to fit the 


buffer. 


1s an integer expression that specifies the length of the 
action buffer. 


is an integer variable that returns the actual length of the 
string in the action buffer. 


is reserved for future use. Specify an integer value of zero 
(0) for this parameter. 


is an integer expression that specifies whether to display an 

Additional Options flag on the menu and whether to return 

control if the user presses the ADDTNL OPTIONS key. Values: 
zero = no flag 


non-zero = display Additional Options flag 


is a string expression of up to 80 characters that specifies 
a message to be displayed on line 23. 


is an integer expression that specifies the length of msgl. 


is a string expression of up to 80 characters that specifies 
a message to be displayed on line 24. 


is an integer expression that specifies the length of msg2. 


@® If you specify a non-zero value for the Additional Options flag, 
POSRES returns (-14/14) in the status block when the user presses 
the ADDTNL OPTIONS key. 


DISPLAY DYNAMIC MENU (DMENU) 


Example: 

1880 REM *** Displaying a single-choice Dynamic Menu. *** 

1890 Act$ = SPACES(80%) !Buffer area of the action string 

1900 Msgl1l$ = 'This is the first message line for the dynamic menu.’ 
1910 Lenl% = LEN(Msgl$) !Length of the first message line 

1920 Msg2S = 'This is the second message line for the dynamic menu.’ 
1930 Len2% = LEN(Msg2$) !Length of the second message line 

1940 CALL Dmenu BY REF & 


(Stb1k%() ,ActS ,80%,Len3% ,0%,0%,Msg1$,Lenl%,Msg2S ,Len2%) 


DISPLAY HELP FRAME (HELP) 


8.5 DISPLAY HELP FRAME (HELP) 


Displays the default help frame or a specified help frame. 


Format: 


status 


frameid 


buflen 


Notes: 


HELP (status, frameid, buflen) 


1S a two-word integer array that returns a code indicating 
the results of the routine call (see Appendix C). 


is a string of up to eight characters that identifies the 
help frame to display. 


is an integer expression that specifies the length of 
frameid. 


@e If you specify a non-existent help frame identifier, POSRES does 
not return an error code in the status block. 


Example: 


1180 REM *** Display help text frame *** 
1190 CALL Help BY REF(Stbl1k%(), 'HELPO0O00', 8%) 
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8.6 DISPLAY MULTIPLE-CHOICE MENU (MMENU) 


This routine displays a multiple-choice menu. 


Format: 


MMENU (status, opt_buff, opt_len, opt count, max_opt, 


status 


Ope. DULE 


opt_len 


opt count 


max opt 


resp _ count 


resp array 


add_opt 


msgl 


buflen 


msg2 


resp count, resp array, add opt, 
msgl, buflen, msg2, buflen) 


is a two-word integer array that returns a code indicating 
the results of the routine call (see Appendix C). 


is a string buffer that specifies the options on this 
menu, in the form of a concatenated string. 


is an integer expresssion that specifies the length of an 
option (up to 64 characters). All options must have the 
same length. Before concatenation, use trailing space 
characters to pad all option strings to this length. 


is an integer expression that specifies the number of 
options in the buffer. 


is an integer expression that specifies the maximum number 
of options that the user can select. 


is an integer variable that returns the number of options 
actually selected. 


is an integer array of the size specified in max_opt that 
returns the ordinal numbers of the selected options in 
ascending order. 

is an integer expression that specifies whether to display 
an Additional Options flag on the menu and whether to 
return control if the user presses the ADDTNL OPTIONS key. 
Values: 

zero = no flag 


non-zero = display Additional Options flag 


is a string expression of up to 80 characters’ that 
specifies text to be displayed on line 23. 


is an integer expression that specifies the length of 
msgl. 


is a string expression of up to 80 characters that 
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buflen 
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specifies text to be displayed on line 24. 


Example: 


2300 
2310 
2320 
2330 
2340 
2350 
2360 
2370 
2380 
2390 
2400 
2410 
2430 
2435 
2440 


2450 
2460 
2470 


2475 
2480 


1s an integer expression 
msg2. 


that specifies the length 


REM *** Setting up to display the Multiple-choice Menu *** 


Optlen% = 6% 


Optct& = 9% 
Opttxts (0%) 
Opttxts$ (1%) 
Opttxts (2%) 
Opttxts (3%) 
Opttxts (43%) 
Opttxts (53) 
Opttxts (6%) 
Opttxts (7%) 
Opttxts (8%) 


"Red iT] 
"Orange" 
"Yellow" 
"Green " 
"Blue " 
"Purple" 
"Brown " 
"Black " 
"White " 


!Maximum option length 

!Option count. 

{Option text. Note that 

!Tool Kit BP2 zero-based arrays 
'are returned in Resary% 

fas 1 through 9, not 

!0 through 8. 


! Now concatenate all the options 
! in one string (Optct% by Optlen$) 


Opt$ = 


of 


OpttxtS (0%) + Opttxt$(1%) + Opttxt$(2%) + Opttxt$(3%) + & 


Opttxt$ (4%) + Opttxt$(5%) + Opttxt$(6%) + Opttxt$(7%) + & 
Opttxt$ (8%) 


Lmt% = 9% 
Msgl$ 
Msg2$ 


REM *** Displaying the Dynamic Multi-Choice Menu. * 


SPACES (75%) 
SPACES (758) 


CALL Mmenu BY REF & 


(Stbl1k%(), Opt$, Optlen%’, Optct%, 
0%, Msgl$, 75%, Msg2S, 


!Max. number of options 
'Buffer area for message line one. 
'Buffer area for message line two. 


k* 


75%) 


Lmt%, Res%, Resary%(), & 
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8.7 DISPLAY SINGLE-CHOICE MENU (MENU) 


Displays a frame from the default static menu buffer. 


Formats: 


status 


action 


buflen 


strlen 


display 


add opt 


msgl 


buflen 


msg2 


buflen 


Example: 


MENU (status, action, buflen, strlen, display, ad_opt, 


msgl, buflen, msg2, buflen) 
is a two-word integer array that returns a code indicating 
the results of the routine call (see Appendix C). 
is a string buffer of up to 80 characters that returns’ the 
action string associated with the option selected. The 


action string is truncated or filled with blanks to fit the 
buffer. 


is an integer expression that specifies the length of the 
action buffer. 


is an integer variable that returns the actual length of the 
string in the action buffer. 


is reserved for future use. Specify an integer value of zero 
(0) for this parameter. 


is an integer expression that specifies whether to display an 

Additional Options flag on the menu and whether to return 

control if the user presses the ADDTNL OPTIONS key. Values: 
zero = no flag 


non-zero = display Additional Options flag 


is a string expression of up to 80 characters that specifies 
a message to be displayed on line 23. 


is an integer expression that specifies the length of msgl. 


is a string expression of up to 80 characters that specifies 
a message to be displayed on line 24. 


is an integer expression that specifies the length of msg2. 


1350 REM *** Calling menu routine *** 

1360 Action$ = Space$( 80% ) !Buffer area for the action string 
1370 Msg1$ = ‘This is the first message line’ 

1385 L1% = LEN(Msgl1S$) !Length of the first message 
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1390 Msg2$ = 'This is the second message line’ 
1400 L2% = LEN(Msg2$) 'Length of the second message 
1410 !0% = display (full) 


1420 CALL Menu BY REF & 
(Stb1k%(),Action$ ,80%,Length% ,0% ,0% ,Msg1S$ ,L1%,Msg2$,L2%) 
1430 10% = add. options (no) : 


FATAL ERROR (FATLER) 


8.8 FATAL ERROR (FATLER) 


The Fatal Error routine informs the user of an unexpected = and 
disabling error condition and returns control to P/OS (not your task). 
It blanks line 22, displays the message "Application error. Press 
RESUME to return to Main Menu." on line 23, and displays an 
application-defined message on line 24. That message can tell the 
user why the application failed and where to look for recovery 
information. | 


Format: 
FATLER (message, buflen) 


message is a string expression of up to 80 characters that specifies 
an error message. 


buflen 1s an integer expression that specifies the length of the 
message parameter. 


Example: 


100 ON ERROR GOTO 1120 


@ 


1120 REM Fatal error handling 


1130 Linenum$S = STRS(ERL) ! Get line number 
1140 Errormsg$ = ERTS(ERR) ! Get error message number 
1150 Rtnmsg$ = 'Fatal error occurred at ' & 

+ Linenum$ + '. ' + Errormsg$ 


1160 L% = LEN(Rtnmsg$) 
1170 CALL Fatler BY REF( Rtnmsg$, L% ) 
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8.9 GET KEYSTROKE (GETKEY) 


Gets a single keystroke from the terminal. The keystroke is not 
echoed on the screen. 


Formats: 


status 


Example: 


100 


GETKEY (status) 


is a two-word integer array containing one of the _ following 


codes: 


first 


word 


+] 


+2 


second 
word 


a DEC Multinational decimal code representing a main 
keyboard key. 


a code representing one of the function keys shown in 
Appendix D. 


indicates an error has occurred. See Appendix C_ for 
status values. 


DIM Stb1k$(1%) 
PRINT "Enter a key "; \ CALL Getkey BY REF( Stblk%() ) 


SELECT Stb1k%(0$%) 


CASE 1 


% 


PRINT "Main keyboard key = "; CHRS$(Stb1k%(1%)) 


CASE 2 


% 


PRINT "Function or Keypad key = "; Stb1k3%(1%) 
CASE ELSE 
PRINT "Error. Status = "3: Stblk%( 0% ), Stblk%( 1% ) 
END SELECT 


GOTO 100 
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8.10 NEW FILE (NEWFIL) 


Solicits the name of a new file to be created by displaying the P/OS 
New File Specification form. 


Format: 
NEWFIL (status, filespec, buflen, strlen, deftype, buflen, 
strlen, text, buflen, msg, buflen) 
status is a two-word integer array that returns a code indicating 


the results of the routine call (see Appendix C). 


filespec is a 50-character string buffer that returns the file 
specification entered by the user. If you specify a default 
file name, it can be no longer than nine characters and must 
be followed by a null character or a space. 


buflen is an integer expression that specifies the length of the 
filename buffer (50). 


strlen is an integer variable that returns the actual length of the 
file specification. 


deftype is a four-character string variable that specifies a default 
file type. If the user changes the file type via Additional 
Options, NEWFIL returns the updated filetype. 


buflen is an integer expression that specifies the length of the 
filetype buffer (4). 


strlen is an integer variable that returns the length of the string 
returned in deftype. 


text is a string expression of 0 to 72 characters that specifies 
text to appear at the top of the form. 


buflen is an integer expression that specifies the length of the 
text string. 


msg is a string expression of 0 to 80 characters that specifies 
text to appear on line 23. 


buflen is an integer expression that specifies the length of msgl. 


NEW FILE (NEWFIL) 


Notes: 
@® A P/OS Diskette application calling NEWFIL must also require 
SYSTEM.MNU in its application installation file. See Chapter 6 
for details. 


Example: 


100 REM Program to test the NEW FILE Service 
110 DIM Stbl1k%( 1% ) 


120 Filename$S = SPACES( 508% ) ! Set up buffer for file name 
130 Filetype$S = '.DAT' ! Set up file name type 
140 Textl$S = ‘Test to check the Service of NEW FILE.’ 
160 Msgl1$ = 'Message at bottom of NEW FILE menu.’ 
180 CALL Newfil BY REF (Stblk3%(), 
FilenameS, 50%, Namelen$%, : 


FiletypeS, 4%, Typelen%, 
Textls, LEN(Text1$), MsglS, piercer 


190 PRINT "Status = ": Stblk%( 0% ), Stblk%( 1% ) 
200 PRINT "Filename = "; Filenames 

210 PRINT "Name length = "; Namelen$% 

220 PRINT "Type length = "; Typelen$% 

230 END 
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8.11 OLD FILE NAME (OLDFIL) 


The Old File Name routine solicits the names of one or more 
files by displaying the File Selection Menu. 


Formats: 


OLDFIL (status, maxfiles, files, strlens, 
wildcard, buflen, textl, buflen, 
msgl, buflen, msg2, buflen) 


status iS a two-word integer array that returns a_ code 
the results of the routine call (see Appendix C). 


existing 


indicating 


maxfiles is an integer variable that specifies the maximum number of 
files the user can select and returns the number of files 


actually selected. 


files is a string buffer that returns the selected file 
Specifications in concatenated 50-character strings, left- 
justified and blank-filled. Thus, the size in characters is 


50 times the number specified in maxfiles. 


strliens is an integer array of the size specified in maxf 


iles that 


returns the actual length of each file specification string. 


wildcard is a string expression that specifies the file selection 
criteria. 
buflen is an integer expression that specifies the length of the 


wildcard string. 


text is a string expression of 0 to 72 characters that 
text to be displayed at the top of the screen. 


buflen is an integer expression that specifies the length 


msgl is a string expression of 0 to 54 characters that 
text to be displayed on line 23. 


buflen is an integer expression that specifies the length 


msg2 is a string expression of 0 to 54 characters that 
text to be displayed on line 24. 


buflen is an integer expression that specifies the length 


specifies 


of text. 


specifies 


of msgl. 


specifies 


of msg2. 


OLD FILE NAME (OLDFIL) 


Notes: 


You can use the default wild-card specification (*.*) by supplying 
a zero-length string, in order to display the latest versions of 
all files in the user's current directory. 


@® The Additional Options “show all versions" and "show only the 
latest versions" work only when you use the default wild-card 
specification. Otherwise, the same file selection menu will 
redisplay. 

@e OLDFIL requires a static buffer, a multi-buffer, and ae $file 
selection buffer, as described in the Tool Kit User's Guide. 

@ A P/OS Diskette application calling OLDFIL must also- require 
SYSTEM.MNU in its application installation file. See Chapter 6 
for details. 

Example: 

100 DIM STBLK%(1%), SIZEARRAY$(1%) 

120 NUMCHOICE% = 2% 

130 FILEBUFS = SPACES (1008) 

140 WILDSPECS = '*.TSK' 

160 TEXT1S = 'Choose a file spec and Press DO' 

180 MSGI1S = 'This is the first message’ 

200 MSG2S = 'This is the second message’ 

230 CALL OLDFIL BY REF & 
(STBLK%(), NUMCHOICE%, FILEBUFS, SIZEARRAY$%(), & 
WILDSPECS, LEN(WILDSPECS$), TEXT1$, LEN(TEXTI1$), & 
MSG1$, LEN(MSG1$), MSG2S, LEN(MSG2S ) ) 

250 PRINT "Status:"; STBLK%(0%), STBLK%(13) 

260 PRINT "Files chosen:"; NUMCHOICE% 

270 PRINT MIDS(FILEBUFS, (I% * 50%) -49%, SIZEARRAY%(I%-1%)) & 


FOR I% = 1% TO NUMCHOICES% 
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OPEN HELP FILE (HFILE) 


This routine opens the specified help definition file and sets’ the 
default help frame. 


Formats: 


HFILE (status, filespec, buflen, frameid, buflen) 


status is a two-word integer array that returns a code indicating 


the results of the routine call (see Appendix C). 


filespec is a string expression that specifies the help definition 


file. 


buflen is an integer expression that specifies the length of the 


help file specification. 


frameid is a string expression of one to eight characters’ that 


specifies the name of the default help frame. 


buflen is an integer expression that specifies the length of the 


default help frame string. 


Notes: 


Only one help file can be open at any time. If another help file 
is open, HFILE closes it before the requested file is opened. 


If your help file is in the application directory, translate the 
logical name "APPLSDIR:" and use the resulting file specification, 
including volume and directory names. A typical translation might 
result in an equivalence name like: 


SYSDISK:[ZZAP00012]TEST.HLP 


If you omit fields, POSRES' uses the P/OS default file 
specification, which is almost certainly wrong. The Tool Kit 
User's Guide has more information about accessing application 
files. 


You must supply a default help frame. Failure to do so results in 
a fatal error. 


OPEN HELP FILE (HFILE) 


Example: 
100 DIM SCB%(7%), STATUS%(1$%) 
! 


! Get name of application directory 
ft 
FILE SPECS = SPACE$(29%) ! buffer for equivalence name 


CALL PROLOG BY REF & 
(SCB%(), 4%, 'APPLSDIR:', 9%, FILE SPECS, 308%) 


! 

! Construct filespec and open help file 
f 

FILE SPECS = FILE SPECS + 'TEST.HLP’ 


CALL HFILE BY REF & 
(STATUS%(), FILE SPEC$, LEN(FILE SPECS), ‘FOO', 3%) 
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OPEN MENU FILE (MFILE) 


This routine opens the specified menu definition file. 


Formats: 


MFILE (status, filespec, buflen) 


status is a two-word integer array that returns a code indicating 


the results of the routine call (see Appendix C). 


filespec is a string expression that specifies the menu definition 


file. 


buflen is an integer expression that specifies the length of the 


menu file specification. 


Notes: 


Only one menu file can be open at any time. MFILE closes any open 


menu file before opening the requested file. 


® If your menu file is in the application directory, translate the 
logical name "APPLSDIR:" and use the resulting file specification, 
including volume and directory names. A typical translation might 
result in an equivalence name like: 

SYSDISK: [ZZAP00012] BASETEST.MNU 

If you omit fields, POSRES' uses the P/OS default file 
specification, which is almost certainly wrong. The Tool Kit 
User's Guide has more information about accessing application 
files. 

Example: 

100 


DIM SCB%(7%), STATUS%(1%) 


! Get name of application directory 
1 
FILE SPECS = SPACE$(29%) ! buffer for equivalence name 
CALL PROLOG BY REF & 
(SCB%(), 4%, 'APPLSDIR:', 9%, FILE SPECS, 30%) 


Construct filespec and open menu file 


FILE SPECS = FILE SPECS + 'TEST.MNU' 
CALL MFILE BY REF (STATUS%(), FILE_SPEC$, LEN(FILE_SPEC$) ) 
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8.14 PACK DYNAMIC SINGLE CHOICE MENU (DPACK) 


This routine packs (stores information in) the dynamic menu buffer. 


Formats: 


The format of a group is: 


status 


fieldid 


buflen 


fieldval 


buflen 


CLRB 


DFLTnn 


KEYWnn 


DPACK (status, group,...) 


is a two-word integer array that returns a code _ indicating 
the results of the routine call (see Appendix C). 


is a string expression of up to six upper-case characters 
that specifies one of the following field identifiers: 


fieldid nn menu field 

ie bal 0) title 

Tex rans 01,02,03 explanatory text 

‘GHLP' global help frame identifier 

'PRMT' prompt text for line 21 

‘OPTNnn’ 01-12 option text for option nn 

‘ACTNnn'! 01-12 action string for option nn 
‘OHLPnn' 01-12 help frame identifier for option nn 


is an integer expression that specifies the length of the 
fieldid. 


is a string variable of any length that specifies’ the 
contents of the field. For example, if fieldid is ‘TITL’ 
then fieldval specifies the title text. 


is an integer expression that specifies the length of the 
field value. 


is a string constant containing a command that clears’ the 
dynamic buffer. 


is a string constant containing a command that sets’ the 
default option number to nn (01-12). 


is a string constant containing a command that specifies the 
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keyword of option nn (01-12). 

offset is an integer expression that specifies the beginning of an 
option keyword as an offset from the beginning of the option 
(range zero to one less than the length of the option text). 


keylen is an integer expression that specifies the length of the 
option keyword. 


Notes: 
@ The order in which you pack menu fields is not significant. 


® If you specify an option help frame identifier (OHLPnn) with an 
invalid (greater than 12) number, POSRES does not return an error 
code in the status block. 


Example: 


1480 REM *** Packing the Dynamic menu buffer. 


1490 TitleS = ‘Title for DYNAMIC Menu’ 

1500 L1% = LEN(Title$) !Length of title field 
1510 Txtl1$ = 'This menu is a shorter version of the FRAMEOO] Menu.’ 
1520 L2% = LEN(Txtl1$) !Length of textl field 
1530 Glbhlip$S = 'HELPOOOO' 

1540 Prmtin$S$ = 'Select the desired option and hit DO' 

1550 L3% = LEN(Prmtin$) !Length of prompt line 
1560 OptltxtS = 'Option 1 - the first choice’ 

1570 L4% = LEN(Optltxt$) !Length of option 1 text 
1580 Opt2txt$ = 'Second option - the default’ 

1590 L5% = LEN(Opt2txts$ ) {Length of option 2 text 
1600 Actstl$ = ‘Action string for the first test option.’ 

1610 L6% = LEN(Actstl$) !Length of action 1 text 
1620 Actst2S = ‘Action string for the second option’ 

1630 L7% = LEN(Actst2$) !Length of action 2 text 
1640 Hlpfrl$ = 'HELPOOOL' 


1650 Hlpfr2s "HELPQOO2' 
1655 ! The Dpack call can be specified on multiple lines. 
! However, the first parameter must always be Status 


1657 REM *** Packing the new Dynamic Single Choice Menu.*** 
1660 Call Dpack BY REF & 
(Stb1k%(), 'CLRB', 4%, 'TITL', 4%, Title$, L1%) 
1680 Call Dpack BY REF & 
(Stb1k%(), 'TEXTO1', 6%, Txt1$, L2%) 
1700 Call Dpack BY REF & 
(Stblk%(), 'GHLP', 4%, GlbhlpS, 8%, 'DFLTO2', 6%) 
1720 Call Dpack BY REF & 


1740 
1760 
1780 
1800 
1820 
1840 


1860 


(Stblk%(), 
Call Dpack 
(Stb1k%(), 
Call Dpack 
(Stb1lk%(), 
Call Dpack 
(Stbl1k%(), 
Call Dpack 
(Stblk%(), 
Call Dpack 
(Stblk3(), 
Call Dpack 
(Stb1k%(), 
Call Dpack 
(Stb1k%(), 
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‘PRMT', 4%, PrmtlinS, L3%) 
BY REF & 


'OPTNO]', 6%, Optltxt$, L4$%) 


BY REF & 
‘OPTNO2', 6%, Opt2txt$, L5%) 

BY REF & 

‘ACTNO1]', 6%, Actstl$, L6$%) 

BY REF & 

'ACTNO2', 6%, Actst2$, L7%) 

BY REF & 

‘OHLPO1', 6%, Hlpfrl$, 8%) 

BY REF & 

'OHLPO02', 6%, Hlpfr2$, 8%) 

BY REF & 

'KEYWOL]', 6%, 0%, 8%, 'KEYWO2', 


(DPACK) 


6%,0% ,6%) 
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8.15 PACK MULTIPLE-CHOICE MENU (MPACK) 


This routine packs (stores information in) the multiple-choice menu 
buffer. 


Formats: 
MPACK (status, group,...) 


The format of a group is: 


status is a two-word integer array that returns a code indicating 
the results of the routine call (see Appendix C). 


fieldid is a string expression of up to six upper-case characters 
that specifies one of the following field identifiers: 


fieldid nn menu field 
gee il 6 title 
'TEXTnn’' 01,02,03 explanatory text 
'GHLP' global help frame identifier 
'PRMT' prompt text for line 21 
buflen is an integer expression that specifies the length of the 


field identifier. 

fieldval is a string variable of any length that specifies’ the 
contents of the field. For example, if fieldid is 'TITL' 
then fieldval specifies the title text. 


buflen is an integer expression that specifies the length of the 
field value string. 


CLRB is a string constant containing a command that clears’ the 
multi-buffer before use. 


Notes: 


@ You can make multiple calls to MPACK. 
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Example: 
2050 REM *** Setting up to pack the multi-buffer ** 
2060 TitleS = ‘Title for Multiple-choice Menu ' 
2070 L1% = LEN(TitleS) !Length of the title field 
2080 Txtl$ = ‘This menu is an example of a Multiple-choice menu. 
2090 L2% = LEN(Txtl$) !Length of the first text line 
2100 Txt2$ ='Use the SELECT key to choose your favorite colors.’ 
2110 L3% = LEN(Txt2$) !'Length of the second text line 
2140 Glbhlp$ = 'HELPOOOO' 
2150 Prmtln$ = 'Use the SELECT key to make a choice and press DO' 
2160 L5% = LEN(Prmtlins$) !Length of the prompt line 
2170 REM *** Packing the multi-buffer. *** 
2180 Call Mpack BY REF & 

(Stbl1k%(), 'CLRB’', 4%, 'TITL', 4%, TitleS, L1%) 
2200 Call Mpack BY REF & 

(Stb1k%(), '‘TEXTO1', 6%, Txt1$, L2%) 
2220 Call Mpack BY REF & 

(Stblke(), "TEXTO2"; Gt, Txt2S, L3%) 
2260 Call Mpack BY REF & 

(Stb1k%(), 'GHLP’, 4%, GlbhlpS, 8%) 
2280 Call Mpack BY REF & 

(Stb1k%(), 'PRMT', 4%, Prmtln$, L5%) 
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8.16 PARSE STRING (PRSCSI) 


This routine parses a string for a CSI sequence. The characters in 
the buff parameter are scanned from the left until a CSI character is 
found. The sequence following the CSI character is parsed and 


translated into a value indicating which function key terminates the 
string. 


Format : 


PRSCSI (status, buff, buflen, csipos) 


Status is a two-word integer array. In the first element of the 
array, +2 indicates that a valid CSI sequence was found and 
that the second element contains one of the function key 
values in Appendix D. A value less than 0 indicates an error 
occurred (see Appendix C). 


buff is a string variable of any length. 
buflen is an integer expression that specifies the length of buff. 


csipos is an integer variable that returns the position of the CSI 
character, counting from one (see notes). 


Notes: 


e® The csipos parameter was described in previous Tool Kit 
documentation as the length of the string, up to but not including 
the CSI character. The value returned is actually the length of 
the string, up to and including the CSI character. 


Example: 
10 Dim Stb1k%(1%) 
30 Buffers = "This is an example of PARSE" + ESC + "[29"" 
40 Call Prscsi By Ref & 
(stblk%(), bufferS, len(buffer$), csipos%) 
50 If stbl1k%(0%) < 0 goto 100 
60 Buffer$S = left$(buffer$, csipos% - 1%) 
70 Print buffers 
80 Print Stblk%(1%) 
90 Goto 200 
100 Print "error"; stb1lk%(0%); stblk%(13%) 
200 End 
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8.17 READ MENU FRAME (MFRAME) 


Reads the specified menu frame into the static menu buffer. 


Formats: 


status 


frameid 


buflen 


action 


buflen 


strlen 


Notes: 


MFRAME (status, frameid, buflen, 


action, buflen, strlen) 


is a two-word integer array that returns a code indicating 
the results of the routine call (see Appendix C). 


is a string of one to eight characters that specifies a menu 
frame identifier. 


is an integer expression that specifies the length of the 
frameid. 


is a string variable of any length that returns the _ global 
action string associated with the menu frame, if present. 
The global action string is truncated or padded with spaces 
to fit the buffer. 


is an integer expression that specifies the maximum length 
of the action parameter. 


is an integer variable that returns the actual length of the 
returned global action string. 


e The menu definition file must be open before calling MFRAME. 


Example: 


1220 Gloact$ = Space$( 80% ) !Buffer for global action string 
1230 CALL Mframe BY REF & 
( Stb1k%(), '‘FRAMEOO1', 8%, Gloact$, 80% , Lens) 


READ MESSAGE (RDMSG) 


8.18 READ MESSAGE (RDMSG) 


This routine read a message from a message definition file into a 


buffer. 


Formats: 


status 


filespec 


buflen 


frameid 


buflen 


message 


buflen 


strlen 


Example: 


RDMSG (status, filespec, buflen, frameid, buflen, 


message, buflen, strlen) 


is a two-word integer array that returns a code indicating 
the results of the routine call (see Appendix C). 


is a string specifying the message definition file. POSRES 
opens the message definition file in the application 
directory (APPLSDIR) unless you supply a directory 
specification. 


is integer expression that specifies the length of the 
filespec parameter. 


is a string expression of 1 to 8 characters that identifies 
the message frame to read from the message file. A fatal 
error results if frameid is specified as blank or of zero 
length. : 


is an integer expression that specifies the length of the 
frameid string. 


is a string buffer of any length that returns the specified 
message. The message is truncated or filled with blanks to 
fit the buffer. 


is an integer expression that specifies the length of the 
message buffer. 


is an integer variable that returns the actual length of the 
returned message string. 


1100 CALL Rdmsg BY REF & 
(Stblk%(),'BASETEST.MSG' ,12%,'MESS0001' ,8%,BS,B%,L3) 


SEND MESSAGE TO MESSAGE/STATUS DISPLAY (MSGBRD) 


8.19 SEND MESSAGE TO MESSAGE/STATUS DISPLAY (MSGBRD) 


This routine sends a message to the P/OS Message/Status 
described in the Tool Kit User's Guide. 


Formats: 


MSGBRD (status, message, buflen) 


Status is a two-word integer array that returns a code indicating the 


results of the routine call (see Appendix C). 


message is a string expression of up to 59 characters that specifies 
text to be sent to the Message/Status Display. 
non-printable characters in the message are replaced 


blanks. 


buflen is an integer expression that specifies the length 
message string. 


Notes: 


@ The MSGBRD routine is not in POSRES; it is in the system 
(SYSLIB). 


@® You must also edit your Application Builder command (.CMD) 
described in the Tool Kit User's Guide. 


Example: 


110 REM Send a message to the message display 
111 Dim Stb1k%(13%) 
112 Msg file$ = "MESSAGES .MSG" 
113 Frame_id$ = "12" 
114 Msg$ = Space$(59%) 
115 Call Rdmsg By Ref & 
(stblk%(), msg _file$, len(msg file$), frame_id$, & 
len(frame _id$), msg$, len(msg$), length) 
116 If stblk%(0%) < 0% goto 500 
140 Call Msgbrd By Ref (Stb1k%() ,MSGS,Length%) 
150 Print Stblk%(0), Stblk%(1) 
160 End 


SPECIFY HELP FRAME (HFRAME) 


8.20 SPECIFY HELP FRAME (HFRAME) 

Specifies the frameid of the frame to be displayed when help is 
requested. This call does not result ina display; it simply defines 
the default frame. 


Format: 


HFRAME (status, frameid, buflen) 


status is a two-word integer array that returns a code indicating 
the results of the routine call (see Appendix C). 


frameid is a string expression of up to eight characters’ that 
specifies the default help frame identifier. A fatal error 
results if frameid is specified as blank or of zero length. 


buflen is an integer expression that specifies the length of the 
frameid string. 


Notes: 
@® The help frame definition file must be open before calling HFRAME. 


e If you specify a non-existent help frame identifier, POSRES does 
not return an error code in the status block. 


Example: 


1140 REM *** Calling help frame *** 
1150 CALL Hframe BY REF(Stbl1k%(), 'HELPOOO1', 8%) 


UNPACK MENU BUFFER (MUNPK) 


8.21 UNPACK MENU BUFFER (MUNPK) 


This routine unpacks (returns the information stored in) the static 
menu buffer. 


Formats: 
MUNPK (status, group,...) 


The format of a group is: 


status is a two-word integer array that returns a code indicating 
the results of the routine call (see Appendix C). 


Fieldid is a string expression of up to six upper-case characters 
that specifies one of the following field identifiers: 


fFieldid nn menu field 

dios a title 

pop. ato ta 01;02;,03 explanatory text 

‘GACT’ global action string 

'GHLP' global help frame identifier 

'PRMT’ prompt text for line 21 

"OPTNnn' 01-12 option text for option nn 

'ACTNnn' 01-12 action string for option nn 

‘OHLPnn' 01-12 help frame identifier for option nn 
buflen is an integer expression that specifies the length of the 


field identifier string. 

fieldval is a string variable of any length that returns the value of 
the field. For example, if fieldid is 'TITL', then fieldval 
returns the title text. 


buflen is an integer expression that specifies the length of the 
field value buffer. 


strlen is an integer variable that returns the length of the field 
value string. 


DFLT is a string constant containing a command that requests’ the 
default option number. 


defopt is an integer variable that returns the default option number 
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KEYWnn is a string constant containing a command that requests’ the 
offset and length of the keyword of option nn (01-12). 

offset is an integer variable that returns the beginning of an 
option keyword as an offset from the beginning of the option 
(range zero to one less than the length of the option text). 

keylen is an integer variable that returns the length of the 
keyword. 

Example: 

1290 TitleS = SpaceS$( 40% ) 'Buffer area for the menu title 


1300 CALL MUNPK BY REF(Stbl1k%(), 'TITL', 4%, Title$, 40%, Lengths) 
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8.22 WAIT FOR RESUME KEY (WTRES) 


This routine echoes all keystrokes except the RESUME key with a bell 
character. When the user presses the RESUME key, control returns to 
your task. You can use this routine to allow the user to read 
something on the screen or change a diskette, for example, before 
proceeding. Before calling WTRES, display a message such as "Press 
RESUME to continue." on the screen. 


Formats: 


WIRES () 


Examples 


1180 PRINT "Calling HELP frame. Press RESUME to continue." 
1190 CALL Wtres BY REF() ! Allow user to read message 
1120 CALL Help BY REF(Stb1k%(), 'HELPO0O00', 8%) 


CHAPTER 9 


PRINT SERVICES 


Print Services consists of a single callable routine that allows your 
application to print a file, stop, continue, abandon or restart a 
print job, or obtain printer’ status. A request to print ae file 
creates a non-interactive task. 


Formats: 
CPRNT (status, request, filespec, len) 
status a two-word integer array used to return a code indicating 
the results of the service request (see below). 
request a 75-word integer array. The first word specifies one of 
the following request values: 


+1 print file 


+2 abandon current print job 

+3 pause current print job 

+4 continue the paused print job 
+5 restart the current print job 
+6 report printer condition 


The remainder of the array is used as a temporary scratch 
pad by the CPRNT routine. 


filespec an ASCII string expression that contains the file 
specification of the file to be printed if the print file 
service (+1) is requested. Specify zero if a service other 
than print file is requested. 


len an integer expression that contains the number of characters 
in filespec. Specify zero if the filespec parameter was 
omitted. 


Print Services 


Status Values: 


+] 


oa 


in the first word of the status array indicates that the request 
was accepted. If the request was ‘report printer condition', the 
second word returns one of the decimal condition codes’~ shown 
below. 


in the first word of the status array indicates that an error 
occurred. The DSW error is contained in the second element of 
the array. 


in the first word of the status array indicates that a print 
service error occurred, and that the second element of the array 
contains one of the decimal error codes show below. 


Condition Codes: 


Oo ON HD OS WD Ee 
@ 


BO NO Fe 
WN © 
° 6 


Print job accepted 

Stop print job accepted 

Pause print job accepted 

Continue print job accepted 
Restart current file accepted 
Print job active 

Print job paused 

Print job inactive 

Printer offline 

Printer offline/paused 

Print request accepted, but printer type does not match 
Unable to determine printer status 


Error Codes: 


scat Oi Ore 


-12. 


3% 
-14. 
Ls 
= 0-3 
cage Soe aa 
ag? oor 
gt ee 
=20is 
a 
-24., 
2s 
= 2 Ov 
Tg a 
320% 
2's 
30s 
eae eee 


Print job already active 

Printer busy 

Printer already attached 

Print job not in progress 

Print job not paused 

Print job already paused 

Parameter out of range 

Printer is offline 

More than 9 files selected 

Printer offline / print job paused 

Illegal file specification length 

Port currently in use 

Mini-~Exchange not connected 

Mini-Exchange printer currently in use 

Print server directive error encountered 
Previous Mini-Exchange connection not broken 
Error accessing Setup file. General RMS error. 
Error accessing Setup file. File access error. 
Error accessing Setup file. Error reading attributes. 
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Notes: 


Error 
Error 
Error 
Error 
Error 
ETrVoOr 
Error 
Error 
Error 
Error 
Error 
Error 
jap ap ek a 
BrEOr 


Print Services 


closing Setup file. 


accessing 
accessing 
accessing 
accessing 
accessing 
accessing 
accessing 
accessing 
accessing 
accessing 
accessing 
accessing 
accessing 


string. 


Error 


accessing 


specification. 


@ On P/OS Hard Disk, 


immediately 


accepted, 


non-interactive 


with 
the 


Setup 
Setup 
setup 
Setup 
setup 
setup 
setup 
setup 
setup 
Setup 
Setup 
setup 
Setup 


Setup 


file. 
file. 
file. 
file. 
file. 
file. 
file. 
file. 
file. 
file. 
file. 
file. 
file. 


file. 


the call to the Print Services 
Status. 
print 


Tf 
service 
application while the calling application goes on 


Bad device specification. 
Bad directory specification. 
No such directory. 

Device not ready. 

File locked by another user. 
File not found. 

Bad node name. 

Privilege violation. 

File processor error. 

File processor error. 

Bad file extension. 

Bad file version number. 
Tllegal wild card in merged 


Extraneous data in file 


always returns 
a request to print a file is 
will print the file as a 


to other processing. 


On P/OS Diskette, the call to Print Services returns status. only 
when the print job is complete or the printer has paused for an 
external reason. The status will reflect this condition. Control 
is returned to the calling application when the print job is 


complete or the printer paused for some other reason. 


must also 
See Chapter 


A P/OS Diskette application that calls Print Services 
list Print Services in its installation command file. 
6 for details. 


CHAPTER 10 


PROSE TEXT EDITOR 


PROSE is the text editor supplied with P/OS. It offers facilities for 
entering and editing text to create documents, source programs, and 
memos or similar text files. Editing keys on the Professional 
keyboard allow text manipulation. The end user documentation 
describes PROSE and the PROSE user interface. 


By calling the PROSE callable editor task (CET), an application can 
offer the text editor for use within its own context. For example, an 
electronic mail application might use the editor to provide editing 
services for message creation or modification. All the editor 
Functions offered to the end user are available in the callable form 
of the editor. 


Application tasks invoke the callable editor task by calling the CET 
Subroutine that resides in SYSLIB. This subroutine invokes a separate 
editor server task to perform the actual editing session. 


Parameters to the CET subroutine define the input and output file 


name, a temporary work file name, format options, maximum line length 
for text entry, and left and right margin values. 


The input file name is the file to be edited. An empty or new file 
can also be created with the newfile parameter. After editing, the 
callable editor opens the output file with the specified name _ to 
create the edited version of the file. 


The CET subroutine passes the specified parameters to the callable 
editor by spawning it as a task. The subroutine waits until the 
editor server task terminates before returning control to the calling 
application. When the editing session terminates, the server task 
returns a two-word status block to the CET routine, which in turn 
passes the status back to the application. The callable editor uses 
EFN (event flag number) 32 so the calling application should not use 
Its | 


Prior to calling the CET subroutine, the calling task should detach 
from the terminal since the callable editor attaches to the terminal 
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during execution. After the callable editor task exits, the calling 
task can reattach to the terminal. For example, if the application is 
written in BASIC-PLUS-2 and attaches the terminal for CTRL/C ASTs, it 
should use RCTRLC to detach the terminal before CET is invoked. 


List the name of the callable editor task in the application 


installation file to make sure that it is installed when the 
application task calls it. (See Chapter 6 for details.) 


Format s 
CET (status, infile, inlen, outfile, outlen, 
workfile, wklen, newfile, format, maxline, 
initleft, initright, initwrap, lun) 

status a two-word integer array that returns the results of the 
editing session as shown in Table 10-1. 

infile a string expression that specifies an input file. The 
default file type is .DOC. 

inlen an integer expression that specifies the number of 
characters in the input file name. 

outfile a string expression that specifies an output file. The 
default file type is .DOC. If the output file is the same 
as the input file, P/OS creates a new version of the file. 

outlen an integer expression that specifies the number of 
characters in the output file name. 

workfile a string expression that specifies a temporary work file. 
The editor task deletes this file on exit. 

wklen an integer expression that specifies the number of 
characters in work file name. 

newfile an integer expression that specifies whether a new source 
file should be created. 
ZeLXO uses an existing file with the name specified in 

infile 
non-zero creates a new file with the name specified in 
outfile 
format an integer expression that specifies whether or not to 


retain escape sequences in the output file (see notes). 
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Zero discards formatting data 


non-zero retains formatting data 


maxline an integer expression in the range 2 to 160 that specifies 


the maximum number of characters on a line that can be 
saved by a user. 


initleft an integer expression in the range 1 to 131 that specifies 


the initial left margin value for a new file. 


initright an integer expression that specifies the initial right 


margin value for a new file. 


initwrap an integer expression that specifies the default word wrap 


setting for a new file. 
Zero disables word wrap 


non-zero enables word wrap 


lun an integer expression that must be present but is ignored 
by the editor task. Specify zero. 
Notes: 
® During the editing session, the user can define margin settings 


for different regions of text that result in the inclusion of 
nonprinting characters, called escape sequences, in the output 
file. The presence of escape sequences in files may cause errors 
if the file is used with host system utilities. If you remove the 
escape sequence from a file, it will print as expected. However, 
if you edit the file again, the margins will be lost. 


Table 10-l: Callable Editor - Status Return Codes 


First Second Meaning 
+] 0 The editing session completed normally. 
+2 0 The editing session completed normally, and the 
output file it produced contains escape 
sequences indicating formatting information 


(for example, margin settings). 


-] DSW code The CET subroutine could not invoke the server 
task. 
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First 


=2 


=, 


=12 


Second 


POSRES code 


RMS code 


RMS code 


RMS code 


RMS code 


RMS code 


RMS code 


PROSE Text Editor 


Meaning 


The Callable Editor Task could not open its 
help file. The second status word contains’ the 
second word of the status block that was 
returned From the execution of the HFILE 
routines in POSRES. 


The Callable Editor Task encountered a problem 
related to the parameters passed to it. The 
second status word has a specific code: 


The server encountered an error while trying to 
receive the parameters from the CET subroutine. 


The parameters contain invalid values. For 
example, the initial left margin value is 
greater than or equal to the initial right 
margin value. | 


The Callable Editor Task could not open the 
specified input file. The second status word 
contains the RMS error code returned in the STS 
field of the FAB when the open failed. 


The Callable Editor Task could not create the 
specified output file. The second status word 
contains the RMS error code returned in the STS 
field of the FAB when the create failed. 


The Callable Editor Task could not create the 
specified work file. The second status word 
contains the RMS error code returned in the STS 
field of the FAB when the create failed. 


The server task encountered a fatal run-time 
error (for example, an odd address trap). 


The input file is not an RMS sequential file. 


An I/O error occurred when writing the output 
file. 


An I/O error occurred when performing I/0 to 
the work file. 


An I/O error occurred when reading the input 
file. 
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First 
-13 
-14 
-15 
-16 

Example: 
10 
20 


Second 


RMS code 


DSW code 


DSW code 


DSW code 


DIM StatBl1k%(1% 
PRINT "Calling 
CALL CET BY REF 
(StatBlk$%(), 
as 0%, 
"MESG.EXC", 88%, 
"SY:W.FIL", 88%, 


5%, 72%, 1%, 


PROSE Text Editor 


Meaning 


The UDK/Setup file could not be opened. The STS 
field of the FAB used to access the file is 
returned in the second status word. 


CET could not create the dynamic region used to 
hold the editor's XBUF buffer pool. 


CET could not create the address window needed 
to map to XBUF. 


An error occurred during a mapping operation to 
access CET's XBUF region. 


) ! Status return data 
CET ..." ! Calling the editor task 


! Return status block. 

! No name since creating new file. 

! Name of resulting output file. 

! Work file used by editor. 

! We're creating a new file. 

! Allow margins; discard ESCapes 

! Let user create long lines. 

i Initial margins 5, 72, word wrapped 
! placeholder - value is ignored 


MM OM MM Bs HM KM 


PRINT 

PRINT "Back from editor. Status block:" 
PRINT " Word 0 =", StatBlk%(03%) 
PRINT “ Word 1 =", StatBlk%(13%) 
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PRO/SORT 


PRO/SORT is a general-purpose sorting utility that runs on P/OS. This 


section discusses how to use PRO/SORT and the commands it supports. 
Error messages are listed in Section 11.13. For a sample PRO/SORT 
command file, see the last section of this chapter. 


11.1 USING PRO/SORT 


Application tasks use the PROSRT routine to invoke and pass to 
PRO/SORT the name of a command file containing sorting commands. The 
parameter list can include the names of an input file (containing 
records to be sorted) and an output file (containing the sorted 
records or indices to the sorted records). 


Formats 


PROSRT (cmdfile, buflen, 
outfile, buflen, 
inpfile, buflen, status) 


cmdfile is a string expression containing a PRO/SORT command file 
specification. The default file type is ".CMD". 


buflen is an integer expression that specifies the number of 
characters in cmdfile. 


outfile is a string expression containing a PRO/SORT output file 
specification. There is no default file type. 


buflen is an integer expression that specifies the number of 
characters in outfile. 


inpfile is a string expression containing a PRO/SORT input file 
specification. There is no default file type. 


buflen is an integer expression that specifies the number of 
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characters in inpfile. 


status is a two-word integer array that receives status information 
from PRO/SORT. 


Include the following in your application installation command (.INS) 
Files 


INSTALL [ZZSYS] PROSORT.TSK/TASK 
INSTALL [ZZSYS] PASRES.TSK/LIBRARY 


Make sure to include a FILE command for each PRO/SORT command file. 
The following is a sample BASIC-PLUS-2 call to PRO/SORT: 


1000 DIM STATUS$3(13%) 
CALL PROSRT BY REF ('TEST.CMD', 8%, 'DATA.OUT', 8%, 
‘'SOURCE.INP', 10%, STATUS$%()) 


Programmers uSing MACRO-11 should note that PRO/SORT uses event flag 
#31. 


11.2 VALID RMS RECORD FORMATS 


The PRO/SORT input and command files can be of variable-length or 
fixed-length sequential record format, independently of each other. 
For example, the input file can have variable-length records and _ the 
command file fixed-length records. The record type for the output 
file matches that of the input file. 


Tf the input file uses variable-length records, the maximum record 
size (MRS) of the output file equals the MRS of the input file. 


Tf the input file uses fixed-length records, there are two 
possibilities for the output file: 


@e If the PRO/SORT command file has WRITE commands, the size of 
the output file equals the total length .of all fields 
specified by the WRITE commands. 


e® If the PRO/SORT command file has no WRITE commands, the 
entire record is copied. Therefore the input and output 
record sizes are identical. 


The maximum record length for a RECORD sort is 400 bytes. The maximum 
record length for a TAG sort is 1005 bytes. The maximum record length 
for an INDEX sort is 1005 bytes. The default is PROCESS RECORD. Lf 
you use a record that is too long, PRO/SORT returns an appropriate 
error message. 
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11.3 PRO/SORT COMMANDS AND COMMAND FILE 


The following sections describe the commands supported by PRO/SORT. 
Where appropriate, the corresponding PDP-11 SORT specification lines 
are also described. If you are familiar with PDP-11l SORT, the 
comparison between SORT and PRO/SORT command syntax may help you 
understand how PRO/SORT can be used to perform familiar SORT 
operations. 


The example at the end of this section illustrates the structure of a 


PRO/SORT command file. During program execution, the command file is 
passed to the sort program and the sort is performed. 


The maximum command line length is 80 characters. Table 11-1 lists 
how many commands are allowed in a PRO/SORT command file. 


Table 1l1-l: Number of PRO/SORT Commands per Command File 


Command Maximum Number of Commands per File 
COLLATE no limit 
DEFAULT 1 

FIELD 20 

FORCE 30 
INCLUDE 20 * 
INPUT i. Ss 
OUTPUT ke 
PROCESS 1 

SORT 16 

WRITE 30: 2% 


Fach condition in an INCLUDE line is counted as an INCLUDE command. 
** you can use the INPUT and OUTPUT statements in the command file only 


if no input or output file is specified in the CALL PROSRT parameter 
list. 


*** Pach field name in a WRITE statement is counted as a WRITE line. 
Comment statements in a PRO/SORT command file are indicated by an 


exclamation point (!) or semi-colon (;) as their first character. For 
example: 


!'This is a PRO/SORT comment. 
This is an alternate form of the PRO/SORT comment. 


By comparison, SORT comments are indicated by an asterisk Ce)! An 
column seven. For example: 


23 


PRO/SORT COMMANDS AND COMMAND FILE 
*This is a SORT comment. 


You can nest indirect command files within the PRO/SORT command file, 
to group related commands. To invoke an indirect command file from 
within the PRO/SORT command file, use the following format: 

@ filespec 


filespec is the name of the indirect command file to be accessed. 
The default file type is ".CMD". 


Indirect command files can be nested 10 levels deep. 


11.4 COLLATE 


Use the COLLATE command to sort and output specific characters in a 
new position relative to the second value specified. For example, you 
can use the COLLATE command to perform country-specific collating 
sequences by changing the logical ordering of a character set. 
COLLATE operates on CHAR fields only. 


Format: 
COLLATE entity, ... 


The format of an entity 1s: 


value value 


value A number or a character. Characters must be enclosed in 
Single or double quotes. 


BEFORE Sorts the first value immediately before the second value. 


AS Sorts the first value as though it were the same as the second 
value. 


AFTER Sorts the first value immediately after the second value. 


If you use the COLLATE command before the DEFAULT command, the 
collating sequence specified by DEFAULT will supersede that specified 
by COLLATE. See the DEFAULT command for further details. 


You can specify an unlimited number of COLLATE commands in the command 
file. 
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11.4.1 COLLATE Compared to SORT ALTSEQ 


SORT performs alternate sequencing of records in a specification file 
through the ALTSEQ command. The format of an ALTSEQ record in SORT 
is: 

ALTSEQ aaabbbxxxyyy... 


aaa The octal value of a character. 
bbb The value of the character to use in the sort. 
XXX The octal value of a character. 
VVV The value of the character to use in the sort. 


The PRO/SORT COLLATE command provides a superset of the same function. 


For example, using SORT to sort commercial at (@) signs as ASCII zero 
(0) characters you would type: 


ALTSEQ 100060 

Using PRO/SORT, you would type: 
COLLATE "@" AS "Q" 

or: 


COLLATE 100 AS 60 


11.5 DEFAULT 


Use the DEFAULT command to set up the default collating sequence. Tf 
you use the COLLATE command before the DEFAULT command, the collating 


sequence specified by DEFAULT will supersede that specified by 
COLLATE. 


The DEFAULT command has one of two formats. If you want to specify a 
country-specific collating sequence, use the following command format: 


Formats: 


DEFAULT | 


language Any of the national collating sequences’ supported by 
PRO/SORT: MULTINAT (DEC Multinational), DANISH, DUTCH, 
ENGLISH, FINNISH, FRENCH, GERMAN, ITALIAN, NORWEGIAN, 
PORTUGESE, SPANISH, SWEDISH, and BINARY. The default is 
MULTINAT. 


USER specifies a user-defined collating sequence. 


LISS 


DEFAULT 


n is an integer representing the binary value of the eight-bit 
character that you want collated at this position. You can 
separate integers with commas or carriage returns. 


The DEFAULT USER command is equivalent to specifying individual 
COLLATE commands for all 256 values of an eight-bit character. 
Therefore, the list must always have 256 integer values. If you 
choose to have all characters treated distinctly (no "collate as"), 
the value of "n" ranges from 0 to 255. For example, 


DEFAULT USER 
4,3,0,1,2,5,6,7,8,9 
10,11,12,... 


02 0 248,249 
250,251,252,253,254,255 


In the above example, character 4 is collated first, followed by 
character 3. The remaining characters are collated normally, in order 
of increasing binary value up to the last character (255). 


If you want to force a character to collate as the preceding character 
in the collating sequence, you must add 1000 to its normal value. For 
example, | 


DEFAULT USER 
1,2,0,3,7,8,12,1013,14,15,4,... 


In this example, character 0 is collated after characters 1 and 2. 
Character 13 is collated equivalent to character 12. 


You can specify only one DEFAULT command in the command file. 


11.6 FIELD 


The FIELD command assigns a symbolic name to a positional range within 
an input record. For example, you could assign the field name "ZIP" 
to columns five through nine in each record, the field name "Address" 
to characters 10-25, and so on. You can define up to 20 fields with 
FIELD commands. 


Once the FIELD command has assigned a symbolic name to a field, other 


PRO/SORT commands reference that field by field name only. You must 
define a field before it can be referenced by other PRO/SORT commands. 
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Formats: 


fname 


datatype 


start 


end 


FTELD 


FIELD fname datatype start end 
A field name (must be a character string). 


One of the following six datatypes: (Figure 11-1 shows’ how 


PRO/SORT interprets bytes as they occur in the input data 
stream). 


CHAR Specifies character data. The field width for this 
data type is equal to the number of characters. 


SINT specifies signed binary integer format. The field 
width must be given as two bytes per number. 


UNSINT specifies unsigned binary integer format. The field 
width must be given as two bytes per number. 


DBLINT specifies double precision binary integer format. 


The field width must be given as four bytes per 
number. 


SPFP specifies single precision floating point. The 
Field width must be given as four bytes per number. 


DPFP specifies double precision floating point. The 
field width must be given as eight bytes per number. 


is an integer representing the starting column number of the 
field within the record. 


is an integer representing the ending column number of the 
field within the record. | 
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Figure ll-l: Mapping of Bytes to Fields in Input Data Stream 


Notes: 


@ For both the SPFP and DPFP data types, the sign appears in bit 
(byte 2), the exponent appears in bits 8 through 15 (bytes 1 and 
2), the mantissa appears in the remaining bits. This conforms 
the standard PDP-1l data type convention. 


Ls 


16 


to 


FIELD 


@® For SINT, UNSINT, DBLINT, the most significant bit is 16, 16, or 
32, respectively. For SPFP and DPFP, bit 15 is the most 
Significant bit of the exponent and bit 7 is the most’ significant 
bit of the mantissa. 


11.6.1 Pseudo-fields RRN and RFA 


Two pseudo-fields are predefined as part of PRO/SORT: relative record 
number (RRN) and record file address (RFA). The relative record 
number is defined as if your command file included the line: 


FIELD RRN SINT x xtl 


where x is the pseudo starting column of the _ field. This two-byte 
number identifies the record’s position in the input file. Use RRN to 
perform random indexing of fixed length sequential files. 


The record file address of a record is defined as if your command file 
included the line: 


FIELD RFA CHAR x x+5 


where x is the pseudo starting column of the field. This 6-character 
identifier provides the block and byte offset of the record in the 
input file. RFAs assist in the random access within a file that 
contains either fixed or variable length records. You can use RFA 
access to retrieve records randomly. 


Use RRN and RFA in any other PRO/SORT command to obtain pointers to 
desired records. For example, the following commands would select the 
first 19 records in the input file and then write the each record's 
location (RFA) and key (KEYFIELDNAME) to the output file. 


INCLUDE RRN < ‘20° 


FIELD KEYFIELDNAME CHAR 1 10 
WRITE RFA, KEYFIELDNAME 


11.7 FORCE 
Use the FORCE command to force any record containing a particular 


field (or a field with a particular value) to a specified position in 
the collating sequence. 
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Format : 
FORCE fname TO val IF val 
fname The field name (must be a character string). 


val A number or a character. Characters must be enclosed in 
Single or double quotes. 


You can use FORCE only on CHAR fields. Where COLLATE affects all 
Fields equally, FORCE operates only on the first character of the 
specified field. FORCE IF operates on that field only if its current 
value is equal to the value specified in the IF clause of the command. 


For example, you could sort the input file so that all zip codes 
appear at the top of the output file: | 


FORCE ZIP TO "0" 


You could also sort the input file so that only the gzip codes 
beginning with 5 appear at the top of the list; all other zip codes 
would be sorted as usual: 


FORCE ZIP TO “0 LF "5° 


You can specify up to 30 FORCE commands in the command file. 


l1.7.1 FORCE Compared to SORT F 


With the SORT F field record specification, you specify the column to 
be forced and the character that column should be forced to. An 
optional trigger character specifies that the force should not occur 
unless the indicated column contains that character. 


The SORT "F" field specifier can also logically combine conditions 
through a FORCE command. PRO/SORT cannot do this. 


For example, using SORT to sort all "X" characters in column 50 as if 
they were "Y"s, you would type: 


FO 50xXY 
To perform a similar sort in PRO/SORT, you would type: 


FIELD NAME CHAR 50 59 


FORCE NAME TO ‘Y‘' IF ‘X' 


ge Ew 8) 


INCLUDE 


11.8 INCLUDE 


Use the INCLUDE command to sort and write to the output file only 
records containing fields that match certain conditions. 


Formats 
INCLUDE condition,... 
The format of a condition is: 


fname operator 2 


The format of an operator is: 


(equal to) 

(not equal to) 

(less than) 

(less than or equal to) 
(greater than) 

(greater than or equal to) 


fname a field name (must be a character string enclosed in single or 
double quotes). 


For example, to select and sort all records whose zip code field, 
"ZIP", begins with "0", you could use the command: | 


INCLUDE ZIP < "10000" 


Fields of data type CHAR can only be compared to other CHAR fields. 
Numeric fields can be compared to any other numeric fields. If a 


constant is specified along with a numeric field, it is assumed to. be 
numeric. 


When you specify more than one condition with a single INCLUDE 
command, PRO/SORT will combine the conditions logically with AND. 
Only records that meet all the INCLUDE line’s conditions will appear 
in the output file. 


When you specify more than one condition with multiple INCLUDE lines, 
PRO/SORT will combine the conditions logically with OR. A record need 
only match one of the INCLUDE lines to appear in the output file. 

You can specify up to 20 INCLUDE conditions in a command file. 

For character fields, INCLUDE can also be used as follows, but only in 


the case of an EQ or NE comparison. It cannot be used for LT, LE, GT, 
or GE. The following examples will illustrate this special case. 


PiSoid 


INCLUDE 


INCLUDE fname = 'XYZ...' 
Include any record that has a field starting with ‘XYZ’. 
INCLUDE fname = '...XYZ' 


Include any record that has a field containing 'XYZ'. 


11.8.1 INCLUDE Compared to SORT O and I 


SORT and PRO/SORT use the same logical relationship tests to determine 
whether an output file will omit or include a given record. When you 
use the SORT I specification, you may either omit or include portions 
of the input file to be sorted. PRO/SORT provides one way to achieve 
either result through an INCLUDE command. 


For example, using SORT to omit all records with column 10 to 14 equal 
to "XYZZY" you would type: 


OC 10 l4EQXYZZY 


With PRO/SORT, you would type: 


FIELD PLUGH CHAR 10 14 
INCLUDE PLUGH NE "XYZZyY" 


Ors 


INCLUDE PLUGH <> "XYZZY" 


11.9 INPUT AND OUTPUT 


The INPUT command specifies which input file contains the data to be 
sorted. The OUTPUT command specifies which file the sorted records 
(or indices to sorted records, for PROCESS INDEX command) are to _ be 
written to. You can use the INPUT and OUTPUT statements in the 
command file only if no input or output file is specified in the CALL 
PROSRT parameter list. 


Format: 
INPUT filespec 
OUTPUT filespec 


filespec a string that specifies the file being sorted or written to. 
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You can specify that file be output to your terminal screen by using 
TI: as the filename. 


11.10 PROCESS 


The PROCESS command specifies whether PRO/SORT uses a RECORD or _ TAG 
sort. 


Formats: 


PROCESS 


For a RECORD or TAG sort, the PROCESS command operates like the /PR 
Switch in SORT. For an INDEX sort, the PROCESS command operates like 
the SORTA address routing sort. 


In a RECORD sort, PRO/SORT manipulates actual records. Use a RECORD 


sort for small sorting jobs. In a TAG sort, PRO/SORT manipulates 
pointers to records. The TAG option can be significantly faster; use 
it for longer records. Switch to TAG if RECORD fails. 


The default is PROCESS RECORD. 


11.11 SORT 
The SORT command specifies the key fields which will be used _ to 


reorder the records in the output file. Specify the key fields in the 
order of their importance to the sort (primary, secondary, etc.). 


Format : 
SORT field, e® @ 8 
The format of a field is: 


fname 


fname The field name (must be a character string). 


A leading plus (+) or minus (-) sign before the field name _ controls 
the order of the sort for the field. A leading plus sign indicates 
that the sort of that field should be performed in ascending order. A 
leading minus sign indicates that the sort should be performed in 
descending order. 
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To specify multiple key fields, you can use more than one SORT command 
Or combine more than one key field on a line. Up to 16 key fields can 
be specified in a command file. 


l11.11.1 SORT Compared to SORT N and O 


Both SORT and PRO/SORT permit key structures (primary, secondary, 
etc.). However, with SORT you can specify a maximum of 10 key fields. 
SORT uses N ("normal") and O ("opposite") in column 7 of the 
Specification file to indicate ascending or descending sort per key. 
PRO/SORT uses the plus (+) and minus (-) signs. 


For example, using SORT to sort the primary key ascending from columns 
1 to 5, secondary descending from 34 to 37, you would type: 


FNC 1 5 
FOC 34 37 


Using PRO/SORT, you would type: 
FIELD PRIMARY CHAR 1 5 


FIELD SECONDARY CHAR 34 37 
SORT +PRIMARY, -SECONDARY 


11.12 WRITE 


The WRITE command creates an output file with a different arrangement 
of fields from the input file. You can use the WRITE command to omit 
a field from the output file, for example, or you can retain all _ the 
fields but output them in a new order. 
Format : 

WRITE fname,... 


fname A field name (must be a character string). 


You can specify up to 30 fields with WRITE commands in the command 
file. 


11.12.1 WRITE Compared to SORT D 


Both SORT and PRO/SORT permit the creation of an output file whose 
records differ in field order from the input file. In SORT, for 
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WRITE 


example, if the input consists of a name in columns 1 to 19, address 
in 20 to 39, and zip in 40 to 44, the output records could be 
rearranged in the order <zip>, <address>, <name> by typing: 


FDC 1 19 
FDC 20 39 
FDC 40 44 


Using PRO/SORT, you would type: 


FIELD NAME CHAR 1 19 


FTELD ADDRESS CHAR 20 39 
FIELD ZIP CHAR 40 44 
WRITE ZIP, ADDRESS, NAME 


11.13 PRO/SORT ERROR CODES 


When PRO/SORT returns control to your program, the first element of 
the status array (element 0) contains one of the following codes: 


1 = normal successful completion 
-l = error occurred in processing 
-2 = could not invoke PRO/SORT 


PRO/SORT is a separate task image on the P/OS system. If it could not 
be invoked, the spawn has probably failed. Check that you have listed 
[ZZSYS] PROSORT.TSK/TASK and [ZZSYS]PASRES.TSK/LIBRARY on the install 
lines of the application installation file. 


If an error occurred in processing, the second element of the status 
array (element 1) contains an error code. 


A code that is greater than zero indicates a PRO/SORT internal error. 
Refer to the PDP-11/SORT Reference Manual. 


A code that is less than zero indicates an error detected by the 


PRO/SORT task. Table 11-2 lists the error codes (decimal) and 
descriptions. 


Table 11-2: PRO/SORT Error Codes 


Error — 
Code (decimal) Description of Error Condition 


-l A command in the sorting command file contains an _ invalid 


parameter, for example a string parameter where a numeric 
parameter is needed. 


1G a 


oa 


PRO/SORT ERROR CODES 


The sort command file contains a line that is not recognized as 
a valid sort command. 


Can't open the specified sort command file. 


An INCLUDE command describes a relation between two fields of 
different data type. 


Two FIELD commands use the same name for their field. 


Multiple INPUT commands. Either the parameter list and the 
command file both contain an INPUT command or the the command 
file contains more than one. 


Multiple OUTPUT commands. Either the parameter list and the 
command file both contain an OUTPUT command or the the command 
file contains more than one. 


A command has spurious text following the normal end of the 
command. 


A fatal error has been found in the logic of the PRO/SORT 
utility. Call the Hot Line. 


Too many FIELD commands have been given. 
Too many FORCE commands have been given. 
Too many INCLUDE commands have been given. 
Too many SORT commands have been given. 
Too many WRITE commands have been given. 


Ellipses were used with a relational operator other than = or 
<> 


No INPUT command was found in the command file stream. 
No OUTPUT command was found in the command file stream. 
A command omitted a required parameter. 


FORCE commands may only be used on fields of type character, but 
a FORCE command was found in violation of this. 


The PRO/SORT data file SYSDISK:[ZZSYS]PROSORT.SYS can’t be 
opened. 


The input file is empty. 
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-22 Can't open the input file. 
-23 Can't open the output file. 
-24 The total size of all key fields added up is too large. 


=25 The user’s command file pool has too many levels of indirect 
command files. 


-26 A field name has been referenced that does not yet exist. 
=o More than one PROCESS soumana in file. 

-28 Too few characters specified with the DEFAULT USER command. 
=29 An input record larger than 1005 bytes has been found. 


-30 Insufficient disk space for temporary files. 


11.14 PRO/SORT EXAMPLE 


Figures 11-2 through 11-5 show several files associated with a sorting 
example. Figure 11-2 shows the PRO/SORT command file. It is designed 
to sort the information in the input file INPUT.DAT (Figure 11-3), 
rearrange it, and output it in a new order to the output file 
OUTPUT.DAT (Figure 11-5). The indirect command file FIELDS.CMD 
(Figure 11-4) is invoked by the PRO/SORT command file. 


Figure 11-2: Sample PRO/SORT Command File 


Command file for sorting the INPUT.DAT file. 
Define the Fields: 


! 
| 
@FIELDS 

! Set up sorting parameters: 


INPUT INPUT.DAT 
OUTPUT OUTPUT.DAT 


SORT Type, LastName 

INCLUDE Type <> "Herol" 

FORCE Type to "0" if "Vv" 

WRITE Type, Space, FirstName, LastName 


oe a eer, 


PRO/SORT EXAMPLE 


Figure 11-3: Sample Input File--INPUT.DAT 
Fake Name2 Hxyzzy 
Fake Name Hardy 
Dick Tracy Hero 
Mary Worth Normal 
Clark Kent Hero 
Peter Parker Herol 
Lex Luthor Villain 
Green Hornet Hero 
Lois Lane Heroine 
Bruce Wayne Herol 
King Tut Villain 
Gen. Zod Villain 
Scooby Doo Herol 
David Banner Hero 
Perry White Normal 
Comm. Gordon Normal 
Mary Jane Normal 
The Joker Villain 
Miss Piggy Normal 
Darth Vader Villain 
Leia Organa Heroine 


The PRO/SORT command file begins with two comment lines, indicated by 
the exclamation points (!): 


Command file for sorting the INPUT.DAT file. 
Define the Fields: 


The first comment identifies the PRO/SORT command file. The second 
introduces the next command line, which invokes and executes the 
indirect command file FIELDS.CMD to define the fields in the input 
file: 


@FIELDS 


Figure 11-4: Sample Indirect Command Files: FIELDS.CMD 


FIELDS .CMD 
! Field specification for the input file INPUT.DAT 
Field FirstName Char 1,7 


Field LastName Char 8,14 
Field Type Char 15,21 
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Field Space Char 7,7 


FIELDS.CMD defines each field in INPUT.DAT and assigns it a symbolic 


name. The field of characters 1-7 receives the field name FirstName; 
the field of character 8-14 receives the field name LastName, and_ so 
On. Once PRO/SORT has executed this indirect command file, the 


program can reference any field in the input file by the field name 
alone. 


The next line in the PRO/SORT command file is another comment: 
! Set up sorting parameters: 


This line identifies the subsequent commands as those which set up the 
sorting parameters for the data file. The sorting parameters 
determine how fields in the data file will be sorted. 


The first sorting parameter specifies the input file: 
INPUT INPUT.DAT 


It identifies INPUT.DAT as the file containing the data to be sorted. 
The next sorting parameter specifies the output file: 


OUTPUT OUTPUT.DAT 


It identifies OUTPUT.DAT as the file to which the sorted records will 
be written. 


If INPUT.DAT and OUTPUT.DAT are specified in the CALL PROSRT parameter 
list, they can't be specified also in the PRO/SORT command file. 


The next sorting parameter is a SORT command: 
Sort Type, LastName 


It specifies which key fields in the input file are pertinent to this 
sort and in what order they will be sorted. The symbolic names Type 
and LastName have already been assigned by the indirect command file 
FIELDS.COM. They are now identified as the primary and secondary 
fields, which will be sorted in the default, or ascending, order. 


The next line is an INCLUDE command: 
Include Type <> "“Herol" 
It specifies which records will be sorted and written to the output 


file. In this case, only records whose field "Type" is not equal to 
"Herol" will be handled by PRO/SORT. Records with the Type "“Herol" 
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will be ignored. 
The next line is a FORCE command: 
Force Type to "0" if "v" 


It specifies that any record with a field type that begins with "v" 
should be sorted and written to the top ("0") of the output file. 


The last line is a WRITE command: 
Write Type, Space, FirstName, LastName 


Using this command, the programmer could have omitted any of the 
fields from the output record. Instead, the programmer has retained 
all fields but specified that they appear in the new order. 


When this program is run, PRO/SORT creates the output file, OUTPUT.DAT 
(see Figure 11-5). 


Figure 11-5: Resulting Output Files OUTPUT.DAT 


Villain The Joker 
Villain Lex Luthor 
Villain King Tut 
Villain Darth Vader 
Villain Gen. Zod 
Hardy Fake Name 


Hero David Banner 
Hero Green Hornet 
Hero Clark Kent 
Hero Dick Tracy 
Heroine Lois Lane 


Heroine Leia Organa 
Hxyzzy Fake Name 2 
Normal Comm. Gordon 
Normal Mary Jane 
Normal Miss Piggy 
Normal Perry White 
Normal Mary Worth 
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APPLICATION DISKETTE BUILDER ERROR MESSAGES 


The Application Diskette Builder displays an error message if it 
cannot continue building a diskette or if it finds an error in the 
-INS file. In the latter case, ADB may respond with more than _ one 
error message for the same error. For example, if the RUN command has 
an error, then two error messages result: 


Invalid task name 
A ‘RUN’ line must be present. 


The normal ADB error messages are listed in alphabetic order in 
Section A.l. 


Some error messages report conditions that you might not be able _ to 


resolve. These error messages indicate that a serious error has 
occurred. In most cases, the errors are the result of a failed file 
operation. These errors are listed in Section A.2 and appear in the 


following form: 


ADB<xxx,yyy> - Message text 


The values xxx and yyy represent error status numbers. These numbers 
correlate to a specific error, which is generally described by the 
message text. These values are positive. Look up the error status 
code in the PRO/RMS-11 manual set. If you cannot determine the cause 
of the error, submit a Software Performance Report (SPR) to DIGITAL. 
Record on the SPR the error message exactly as it was displayed on the 
terminal, including the values represented here as <xxx,yyy>. 


A.1 ADB NORMAL ERRORS 


A 'NAME’ line must be present 


ADB NORMAL ERRORS 


The application installation file does not contain a NAME "menu name" 
line. 


A NAME "menu name" must be present in each application installation 
file. The NAME “menu name" line assigns a default name to this 


application. Correct the application installation file and _ restart 
the ADB. 


A ‘RUN’ line must be present 


The application installation file does not contain a RUN’ taskname 
line. | 


The application installation file must have, as the last line of the 
file, a RUN taskname _ line. When the application is invoked, P/OS 


executes the task listed in the RUN line. Correct the application 
installation file and restart the ADB. 


An ‘INSTALL/TASK’ line must be present 


Either the application installation file does not contain an INSTALL 
line or the INSTALL line(s) contain syntax errors. 


INSTALL lines list all the programs that PRO/Dispatcher must install 


to run this application. Correct the application installation file 
and restart the ADB. 


At least one ‘FILE’ line must be present 


Either the application installation file does not contain a FILE line 
or the FILE line(s) contain syntax errors. 


FILE lines list all the files that must be copied to the target 
diskette. Correct the application installation file and restart the 
ADB. 


Copy aborted 


An error occurred while the ADB was copying files to the 


Error <xxx,yyy> creating directory <dirname>. 


The ADB could not create a directory specified in the FILE or REQUIRE 
command line. 


Check the installation file and try again. 
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Invalid number or too large. -- Try again. 

The number of blocks to allocate for a checkpoint file was entered 
incorrectly. 

Invalid switch for this command line 

The application installation file has an invalid switch. 


Correct the application installation file and restart the ADB. 


Invalid syntax for this command 


The application installation file contains unrecognized characters at 
the end of a line. 


Correct the application installation file and restart the ADB. 


Invalid task name. 


A line in the application installation file that accepts task file 
names lists an invalid task name. 


Task names can be no more than 6 characters’ long. Correct the 
application installation file and restart the ADB. 
/LIBRARY and /COMMON switches must precede /TASK switches on INSTALL 


lines 


An INSTALL/TASK. line in the application installation file occurs 
before an INSTALL/LIBRARY or INSTALL/COMMON line. 


Correct the application installation file and restart the ADB. 


Not enough contiguous space on the volume for <filename> 


The file <filename> requires contiguous space and could not be copied 
to the remaining free space on the diskette. 


Use a different diskette with more free space on it, or try to use the 
same diskette by changing the order in which files are copied. 


To reorder the way in which files are copied, list task images’~ and 
files that are built to reside in contiguous or adjoining blocks first 
in the FILE lines of the application installation file. After 
contiguous files are copied, the remaining fragmented space can be 
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used to store files that do not require a contiguous area. 


Not enough room on this diskette for the application directory. 


The main ADB screen is displayed. 


Not enough space left on the diskette for <filename> 


During the copy operation the diskette filled up before the file 
<filename> could be copied to it. 


Start over with another diskette. 


Only one ‘ASSIGN HELP’ line is allowed 


The application installation file contains multiple ASSIGN HELP lines. 
Only one line of this type is permitted. 


The ASSIGN HELP line assigns a default help definition file to this 
application. Correct the application installation file and restart 
the ADB. 


Only one ‘ASSIGN MENU’ line is allowed 


The application installation file contains multiple ASSIGN MENU lines. 
Only one line of this type is permitted. 


The ASSIGN MENU line assigns a default menu definition file to this 
application. Correct the application installation file and restart 
the ADB. 


Only one ‘NAME’ line is allowed 


The application installation file contains multiple NAME "menu name" 
lines. 


Only one line of this type is permitted. The NAME "menu name" line 
assigns a default menu name to this application. Correct the 
application installation file and restart the ADB. 


Only one ‘RUN’ line is allowed 


The application installation file contains multiple RUN taskname 
lines. 


ADB NORMAL ERRORS 


The application installation file must have, as the last line of the 
file, a RUN taskname line. When the application is’ invoked, 
PRO/Dispatcher executes the task listed in the RUN line. Correct the 
application installation file and restart the ADB. 


Please enter a valid alphanumeric name. 


Bither no characters were entered or invalid characters were entered. 


The file name is invalid 


A file name in the application installation file is not a correct 
PRO/RMS-11 file specification. 


Correct the application installation file and restart the ADB. 


The frame identifier is incorrect 


A frame identifier (frameid) in the application installation file is 
not in the correct format. 


Check the help definition file to make sure you are spelling the 
frameid correctly. Correct the frame identifier in the application 
installation file and start again. 


The Installation file command lines are in an incorrect order 


The application installation file contains lines that are not in 
correct order. 


Review the application installation file format and correct the errors 
in the file. Restart the ADB. 
The string must be quoted and within length boundaries 


A string, such as the "menu name" string in the NAME line, is_ not 
surrounded by quotes or contains too many characters. 


See the description of the syntax of strings in an application 
installation file. Correct the application installation file and 
restart the ADB. 


The volume name is invalid. 


The volume name in a MOUNT line is not a 1l- to 12-character 
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alphanumeric string. A volume name in a MOUNT line cannot include a 
Colon Cs). 


Correct your volume name and try again. 


This command is invalid 

An invalid command is listed in the application installation file. 
Check the list of valid commands in the section on application 
installation files. Correct the application installation file and 
restart the ADB. 


Unable to bad block the diskette in <drive> -- Try another. 


The diskette in the named drive could not be bad blocked as part of 
the initialization. 


Replace the diskette and try the operation again. 


Unable to locate the file <filename>. 


The application installation file could not be located in either’ the 
current directory or in the specified new directory. 


Check to be sure the installation file is in the specified directory. 
Specify the correct application installation file. 


A.2 ADB SERIOUS ERRORS 

ADB<xxx,yyy> - Cannot access menu file 

The ADB menu file could not be accessed. 

Try running the ADB again. If you receive the same error message, 
submit an SPR. 

ADB<xxx,yyy> - Error creating this directory -- Try another. 

The destination directory could not be created on the target diskette, 
possibly because the diskette has bad blocks or format errors. The 
error code corresponds to either a PRO/RMS-11l error code or an “I/O 


error code. 


Fither try another directory or restart the ADB with a new diskette. 
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ADB<xxx,yyy> ~- Error while gathering additional user directories. 


An error occurred while the ADB was gathering additional user 
directories. 


Submit an SPR. 


ADB<xxx,yyy> - RMS error accessing the installation file. 


The application installation file could not be opened because of a 
record access error. 


Check the diskette to make sure it contains an .INS file. If it does, 
make sure you have named the .INS file with a .INS file type. Look up 
the PRO/RMS-11 I/O error codes in the PRO/RMS-11 manual set, and 
restart the ADB. If you receive the same error message, submit an 


SPR. 

ADB<xxx,yyy> - RMS error connecting to <filename> 

The ADB could not access the file listed as <filename>. 

Look up the PRO/RMS-11 I/O error codes in the PRO/RMS-11 manual set. 
Try running the ADB again. If you receive the same error message, 
Follow the procedures for submitting an SPR. 

ADB<xxx,yyy> - RMS error creating <filename> 

The ADB could not create the file listed as <filename>. 

Look up the PRO/RMS-11 I/O error codes in the PRO/RMS-1l1 manual set. 
Try running the ADB again. If you receive the same error message, 
follow the procedures for submitting an SPR. 

ADB<xxx,yyy> ~- RMS error opening <filename> 

The ADB could not open the file listed as <filename>. 

Look up the PRO/RMS-11 I/O error codes in the PRO/RMS-11 manual _ set. 
Try running the ADB again. If you receive the same error message, 
follow the procedures for submitting an SPR. 

ADB<xxx,yyy> - RMS error while reading <filename> 


The ADB could not read the file listed as <filename>. 


ADB SERIOUS ERRORS 


Look up the PRO/RMS-11 I/O error codes in the PRO/RMS-1ll manual set. 
Try running the ADB again. If you receive the same error message, 
follow the procedures for submitting an SPR. 


ADB<xxx,yyy> - RMS error while writing to <filename> 

The ADB could not write to the file listed as <filename>. 

Look up the PRO/RMS-11 I/O error codes in the PRO/RMS-11 manual _ set. 
Try running the ADB again. If you receive the same error message, 
follow the procedures for submitting an SPR. 

ADB<xxx,yyy> —- Unable to access directory listing. 


The directory of the specified device could not be obtained. A_ fatal 
error message is displayed. 


Check to be sure the directory resides on the specified device and 
that the device is properly loaded. Try the operation again. If you 
receive the message again, submit an SPR. 


APPENDIX B 


FDT ERROR MESSAGES 


FDT displays two types of error messages: user errors and internal 
errors. 


User error messages are intended to be self-explanatory. If you need 
clarification or advice, this appendix contains an alphabetic* list of 
user error messages and possible solutions. A symbol enclosed in left 
and right angle brackets (< and >) represents a field name, frame 
identifier, or file specification that FDT has copied from your 
command or retrieved from stored information. Internal error messages 
indicate that a serious error has occurred in FDT processing. In most 
cases, they result from a file operation failure. They appear in the 
following form: 


FDT<xxx,yyy> - Message text. 


The values xxx and yyy represent PRO/RMS-11 I/O error status numbers 
and correlate to a specific error which is generally described by the 
message text. When you see an internal error message: 


1. Record the error message exactly as it was displayed on your 
terminal, including the numbers enclosed in angle brackets. 


2. Exit FDT (enter the SAVE or EXIT command). 


3. Invoke FDT and use the REPORT command to obtain a hard copy 
listing of the file. 


4. Look up the error status code in the PRO/RMS-11 manual _ set. Le 
you cannot determine the cause of the error, submit a Software 
Performance Report (SPR) to DIGITAL. Include a detailed 
description of the user-FDT dialogue up to and including the error 
message, and the report file, if possible. 


* The error messages are sorted on the text, not the symbols. 
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USER ERRORS 


B.l1 USER ERRORS 

Action form deleted. 

An option description line was deleted or the keyword in an _ option 
description line was’ divided onto two lines on a Display form. The 
action form for the option description line was deleted by FDT. An 
Action form is deleted if the option it describes no longer exists. 

If you deleted the option description line, create another one. When 
you create the new one, an action form will be set up for it. If you 
divided a keyword onto two lines on the Display form, enter it on only 
one line. A new action form will be set up for it. 


<Frame-id> already exists - name of frame unchanged. 


The NAME command specified a previously assigned frame identifier as a 
new frame identifier. 


Use the LIST or REPORT commands to check the names of existing frame 
identifiers. 

<Frame-id> already exists - no new frame created. 

The frame identifier of an existing frame was specified in an ADD 


command. Use the MODIFY command to alter the existing frame or enter 
a unique frame identifier. 


<filename> already saved. 

The current file was not changed, so no new copy of the file has’ been 
created. Control returns to host system command level. 

Default option is not in the range 0 to xx. 

The default option field on a Profile form has a value outside the 
valid range. The valid range is zero to xx, where xx is the total 
number of option description lines on the Display form. This error 
condition is detected after use of the CONVERT command. 

Use the MODIFY command to alter the Profile form to contain a value in 
the range. 

Default option specified with no options. 


A value was specified in the default option field on the Profile form 


Bez 


USER ERRORS 


but no options were listed on the Display form. This error condition 
is detected after use of the CONVERT command. 


Create two or more options in a Display form. Check to make sure the 
default option field on the Profile form is correct. 


<frame-id> does not exist. 


A frame identifier was specified with the Modify, Name, or DELETE 
command, but it does not exist in the current file. 


Check for typograhical errors in the frame identifier. To display the 
list of frames contained in the current definition file, type a 
carriage return. Then use the LIST command to display the frame 
identifiers. 


Enter *H", "M" or "S" to select a file type, or a return. 


A character other than H, M, or S was entered in response to the 
previous prompt. 


To select a file type, respond to the prompt by entering the _ single 
character in parentheses in the message. The file type determines the 
type of frames that may be created and stored in the current 
definition file. To specify a new definition file, enter a carriage 
return. The prompt Filename: will be displayed. 


Field <name> invalid in action form <number>. 

The named field, which is on the Action form with the indicated 
number, does not contain valid information. This error is detected 
after use of the CONVERT command. 

Use the MODIFY command to fix the specified field. The most likely 
reason for this error message is a blank value for a required field. 


Field <name> invalid in display form. 


The named field, which is on a Display form, does not contain valid 
information. This error is detected after use of the CONVERT command. 


Use the MODIFY command to fix the specified field. The most likely 
reason for this error message is a blank value for a required field. 


Field <name> invalid in profile form. 


USER ERRORS 
The named field, which is on the Profile form, does not contain valid 
information. This error is detected after use of the CONVERT command. 
Use the MODIFY command to fix the specified field. The most likely 
reason for this error message is a blank value for a required field. 
File <filename> is empty. DELETE command is invalid. 
An attempt was made to delete a frame that doesn't exist. No frame is 
deleted. 
File <filename> is empty. File not written. 


There are no frames ina file that was to be saved. The file is not 
saved and control returns to host system command level. 


Make sure the correct file was specified or use the QUIT command to 
leave FDT after opening an empty file. 

File <filename> is empty. MODIFY command is invalid. 

The MODIFY command was typed but no frames are available for 
modification. 

File <filename> is empty. NAME command is invalid. 


The NAME command was typed but no frames are available to rename. 


File <filename> is not an FDT source file - try again. 


The specified file is not a valid FDT definition file or FDT will 
prompt you again for the filename. 


File <filename> not found. 


Either the specified file is not a valid FDT definition file, or _ the 
file does not exist. 


Create a new FDT definition file using the specified name or enter a 
carriage return to enter a different file name. 


No frames written to converted file. 


The CONVERT command specified a definition file but it contains no 
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valid frames that may be converted. All frames in the current 
definition file contain errors. 
Fix the errors in the frames, and then use the CONVERT command to 
convert the file. | 
Frame identifier may only have alphanumeric characters. 


The specified frame identifier contained characters that are not in 
the ASCII alphanumeric character set. 


Frame identifiers must be specified with ASCII alphanumeric characters 
only (A through Z and 0 through 9). 
Frame <frame-id> not converted. 


The named frame was not converted because it contained invalid 
information or it lacked required information in one or more fields. 


Use the MODIFY command to fix the listed errors. Then use the CONVERT 
command to convert the frames. 

Invalid command. Enter HELP for a list of commands. 

An invalid command was entered. 

Review the list of valid commands in the FDT documentation, or _ type 
HELP to display the list of valid commands. 

Invalid file specification <filename>. 

An error was made in the format of the file specification. 

Check for typographical errors in the file specification and retype if 


necessary. Refer to the Tool Kit User's Guide or your host system 
documentation for more information on file specifications. 


Invalid identifier. 


A frame identifier was specified with more than eight characters, or 
with characters that are not in the ASCII alphanumeric character set. 


Enter a frame identifier with no more than eight characters in _ the 
ASCII alphanumeric character set (A through Z and 0 through 9). 


USER ERRORS 


Keyword deleted. 

The keyword for the option description line that was just altered was 
deleted. Keywords are deleted whenever the keyword no longer matches 
the option description line. 

Enter a new keyword for the new option description line. 

Keyword does not match description line. 

The value entered in the keyword field on an Action form is’ invalid. 
It does not match any segment of contiguous characters in the option 
description line on the Display form. 

You must either leave the option keyword field blank or enter a 
unique, matching keyword in the keyword field. 

Keywords not unique for options xx and yy. 

Two matching keywords were specified for the named options. Either 
keyword xx iS a subset of keyword yy or vice versa, or they are 
identical. For example, “cat" is a subset of "catch" and the number 1 
is a subset of the number 10. This error condition is detected after 
use of the CONVERT command. 

Alter the keyword for one or both of the specified options. Do not 


delete an option description line on the Display form to alter it. If 
you delete the line, the action form for the option will be deleted. 


No action form found for option xx. 


An action form was not filled in for the named option. This error 
condition is detected after use of the CONVERT command. 


Use the MODIFY command to fill in the Action form. 


No frames to report. 


A report on the current definition file was requested but the file 
contains no frames. 


Make sure that the correct file is open. 


No matching option found. 


A nonexistent option was specified in the ACTION command. 


USER ERRORS 


Check for typograhical errors in the command line. Review the list of 
options on the Display form. 


No new options found. 


The ACTION NEW command was specified but all options have been 
assigned actions. 


Use ACTION ALL or ACTION option-number to modify the desired options. 


No option lines defined. 


The ACTION command was used but no option description lines have’ been 
specified. 3 


Use the DISPLAY command to enter the option description lines, and 
then use the ACTION command to assign actions to each option. 


No value entered for required field. 


This is a warning message indicating that the previous field requires 
a value before this frame can be converted. 


Determine what the value should be for the previous field and _ enter 
that value in the field before attempting to convert the file. 


Not enough room to insert a line. 
There is not enough room in the field to open a new line. 


Use the arrow keys or the next and previous field keys on the FDT 
editor keypad to make room. 


Please answer Yes or No. 


You have responded incorrectly to a prompt requiring a Yes or No 
response. 


Respond with a Y for Yes, or an N for No. 


Please enter FULL, TOP, BOTTOM. 
The value entered for the field is not one of the valid values listed. 


You cannot proceed to the next field without entering a_ correct 
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response. Enter Full, Top, or Bottom to specify the display location 
of a help text frame. Initially, FULL is the value in the location 
field. To replace FULL or an entered value, use the arrow keys to 
position the cursor on the F, then press the DELETE WORD key on_ the 
FDT keypad and enter a correct value. 


Please respond with an "M”" or “"T". 


Before you can add a frame in a help definition file, you must specify 
whether you are adding a help menu or a help text frame. 


Enter an "M" to add a menu, a “T" to add a text frame, or carriage 
return to display the file command prompt. 


Value must be between O and 12. 


A value was entered for the default option field but tthe value is 
neither an integer between zero and 12 nor a blank. 


You cannot proceed to the next field without entering a correct 
response. The maximum number of options on a menu is 12. You can 
assign any one of the 12 options to be the default option. If you 
assign an option to be a default, when the menu is displayed the 


selector will rest by the default option. Enter a valid numeric value 
for the field or leave it blank. 


B.2 INTERNAL ERRORS 

FDT<xxx,yyy> - Cannot create output file. 

The output file specified in the CONVERT command cannot be written 
because of a processing error. 

FDT<xxx,yyy> - Cannot create temporary file. 

The file specified cannot be opened because of a processing error in 
the file manager. 

FDT<xxx,yyy> - Cannot display graphics frame. 

A processing error occurred while FDT was attempting to display a 
form. 


FDT<xxx,yyy> - Cannot read frame <frame-id>. 


Bae 


INTERNAL ERRORS 
An attempt to read the specified frame failed. 


FDT<xxx,yyy> - Cannot read frame from temporary file. 

This error indicates that a record is inaccessible from the MODIFY 
command. 

FDT<xxx,yyy> - Cannot read record. 


A record in the current file cannot be accessed for conversion. 


FDT<xxx,yyy> ~- Cannot read record <frame-id> from temporary file. 

The named frame cannot be converted because of a processing error. 
FDT continues to convert the remaining records in the file. 
FDT<xxx,yyy> - Cannot write index of converted file. 

The output file from the Convert process has been corrupted. Under no 
circumstances should the output file be used on the Professional. 
FDT<xxx,yyy> - Cannot write record <frame-id>. 


The named frame cannot be converted because of a processing error. 
FDT continues to convert the remaining records in the file. 


FDT<xxx,yyy> - Cannot update index record for frame <frame-id>. 

The named frame cannot be converted because of a processing error. 
FDT continues to convert the remaining records in the file. 
FDT<xxx,yyy> - Closing original file after copy. 

The file specified cannot be opened because of a processing error in 
the file manager. 

FDT<xxx,yyy> - Could not read file index zz. 

The specified file cannot be opened because the file index cannot _ be 


read. 


FDT<xxx,yyy> - Frame <frame-id> unreadable. 


INTERNAL ERRORS 
The specified frame exists in the file but it cannot be read. 


FDT<xxx,yyy> —- Index not written to data file. 

The current file cannot be saved in a permanent file because of a 
processing error. 

FDT<xxx,yyy> - New file cannot be created. 

The current file cannot be saved in a permanent file because of a 
processing error. 

FDT<xxx,yyy> - Read #zz during initial copy. 

The specified file cannot be opened because of a processing error in 
the file manager. 

FDT<xxx,yyy> - Record <frame-id> could not be written to data file. 
The named frame cannot be saved in the permanent file because of a 
processing error. 

FDT<xxx,yyy> - Record <frame-id> unreadable from temporary file. 

The named frame cannot be saved in the permanent file because of a 
processing error. 

FDT<xxx,yyy> - Unable to write record. 


The frame editor cannot write the last record to the file. 


FDT<xxx,yyy> - Write #zz during initial copy. 


The file specified cannot be opened because of a processing error in 
the file manager. | 


APPENDIX C 


POSRES STATUS BLOCK CODES 


POSRES uses the status block parameter to return error and status 
information to the calling program. It is recommended that your task 
check the status block after each POSRES call. 


Decimal status values are returned to the calling task in a two-word 
integer array. The first column of Table C-1l shows the values 
returned in the first word of the status array. The second column 
lists the values returned in the second word of the status array, 
except for menu routine errors, which are shown in Table C-2. 


In Table C-1, the numbers one and two represent the first and _ second 
status block words, respectively. In your application, the first word 
may be array element zero, one, or n, depending on which programming 
language you are using. For example, BASIC-~PLUS-2 numbers arrays from. 
zero while PASCAL lets you define your own numbering scheme. 


Table C-l: POSRES Status Values 


Status Block Words 


1 2 Description 

+] 1 through 12 For menus, option selection was successful and 
the second word contains’ the ordinal option 
number. 

ASCII code For GETKEY, the second word contains an ASCII 
decimal code representing a keyboard key. 
Undefined For other routines, there was no error. 
+2 0 A record or field was truncated. 


Table C-1 (cont.) 


Key code 


Key value 


-] DSW 
—2 I/O code 
-3 
-] 
-2 
-3 
-4 
-5 
—4 See Table C-2 
-5 See Table C-2 
-6 See Table C-2 
-7 -ll 
-12 
-13 
-9 
-10 0 
-1l 
-] 


-12 RMS error code 


-13 See Table C-2 


POSRES STATUS BLOCK CODES 


Description 


A message sent to the message board 
truncated to 59 or fewer characters 
displayed. 


For GETKEY, the second word contains one of 
function key codes listed in Appendix D. 


For PRSCSI routine, a valid CSI sequence 
entered. 


was 
and 


the 


was 


RSX DSW error. See the P/OS System Reference 


Manual for error codes. 


I/O status error code returned from a 


OIOS 


directive. See the P/OS System Reference 


Manual. 

File access error. 

Index record not 256 bytes long 

No match during index operation 

File index record is greater than one block 
File is not open 

Frameid is not in Radix-50 character set 
Error executing help routine. 

Error executing menu routine. 

Error executing dynamic menu routine. 
Invalid CSI sequence found 

No CSI sequence found 

File extension error 

Calling parameter error 

Insufficient buffer space 

Short message error 


No matching entry number 


PRO/RMS-11 File access error. See 
PRO/RMS-11 manual set for error codes. 


Error executing menu unpack routine. 
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POSRES STATUS BLOCK CODES 


Table C-l (cont.) 


1 2 Description 
-14 Key code Option selection failed. The second word 
contains one of the function key codes’ listed 
in Appendix D. For example, the value 14 
indicates that the user pressed the ADDTNL 
OPTIONS key. 
~ 15 See Table C-2 Error displaying frame specified with frameid. 
-16 See Table C-2 Error executing multiple-choice menu routine. 
=A] See Table C-2 Error executing menu pack or unpack routine. 
a | Error executing OLDFIL routine. 
-] No choices made 
~2 No files found 
=3 Error in wildcard selection 
-19 Buffer error. The buffers FLSBUF and MMSBUF are 
not large enough. 
-20 -] Message rejected. The Message/Status Display is 
. full. The Display lists up to 255 messages. 
Table C-2: Menu Service Routine Errors 
Word Two Description of Error 
~1 Option number greater than maximum 
~2 Multiple once-only fields 
—4 Error in keyword definition 
-5 Title or text field length error 
—6 Text field length error 
-8 Argument error or unknown fieldid 
-9 Buffer error 
-10 Text or option line number greater than maximum 
-ll Error in menu packing 
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POSRES STATUS BLOCK CODES 


Table C-2 (cont.) 


Word Two Description of Error 

-12 No options for multiple-choice menu 

~13 Multiple-choice menu limits responses to zero 
-14 More responses allowed than options 

= 15 No help available 


APPENDIX D 


FUNCTION KEY NAMES AND CODES 


Code PRO Label P/OS Label 

1 Fl Fl 

2 F2 F2 

3 F3 BREAK 

4 F4 SETUP 

5 F5 F5 

6 F6 Reserved 

7 F7 RESUME 

8 F8 CANCEL 

9 | F9 MAIN SCREEN 
10 F10 EXIT 
11 F1l F1l 

12 F12 F12 

13 F13 F13 

14 F14 ADDTNL OPTIONS 
15 HELP HELP 

16 DO DO 

Li? Fl7 Fl’ 

18 F18 F18 


Al 


42 


FUNCTION KEY NAMES AND CODES 


PRO Label 


F19 

F20 

FIND 

INSERT HERE 
REMOVE 
SELECT 

PREV SCREEN 
NEXT SCREEN 
up arrow 
left arrow 
down arrow 
right arrow 
PFI 

PF2 

PF3 


PF4 


(Application Mode only) 


minus 
comma 
period 
ENTER 
0 


1 


P/OS Label 


F19 

F20 

FIND 

INSERT HERE 
REMOVE 
SELECT 

PREV SCREEN 
NEXT SCREEN 
up arrow 
left arrow 
down arrow 
right arrow 
PFl 

PF2 

PF3 


PF4 


FUNCTION KEY NAMES AND CODES 


Code PRO Label P/OS Label 
43 a A 
44 5 5 
45 6 6 
46 I ri 
47 8 8 
48 9 9 


APPENDIX E 


P/OS ERROR CODES 


P/OS displays error codes in the following situations: 


E.l 


An application cannot be started. In this case, the 
PRO/Dispatcher displays an error code in the form of two decimal 
numbers. These error codes are listed in Section E.l. 


An application task exits abnormally (with exit status other than 
EXSSUC). The PRO/Dispatcher displays (in decimal numbers) the 
First two words of the exit status block. If the exit status (the 
First word) is four (EXSSEV), something in the task caused the 


system to abort. In that case, the second word is also 
significant. The error codes for this case are listed in Section 
Bw2s 


The system stops working and displays a picture of a Professional 
with none of the hardware components highlighted. In the case, 
the Executive displays two octal bugcheck error codes. These are 
listed in Section E.3. If you see one: record the codes as well 
as a description of the state immediately prior to the crash, and 
call the Hotline. 


APPLICATION CANNOT BE STARTED 


Elements of the Status Array 


axa CD <TD OOD a CTD Ge GED EL cEE GE ce <a cD cme oD GED aE ems GE au a> exe EP GED Ce <= em aD eee «=D GP eu aD «me cD OD a= 62 «ED 2D =D GUD OED e=m OED ama aD OED aD EUND GED MED ED GEE CRED GD GEED ED eORID CRD CRD OD GMD COED 


t Second 
Word Meaning 
0 The .INS file is missing or cannot be opened. 
nxx The .INS file contains errors. 


The status number in the error code lists the 
INS file line (n) which contains the error 
followed by numbers (xx) which mean the following: 


E-1 


NXX 


APPLICATION CANNOT BE STARTED 


00 RUN line expected 

O01 invalid parameter count 

02 invalid first keyword 

03 invalid filename spec 

05 invalid string on line (improperly quoted) 
06 invalid frameid 

07 extra characters on line 

08 invalid task name 


An application task cannot be installed. 

The status number in the error code lists the 

~-INS file line (n) which contains the error 
followed by numbers (xx) which mean the following: 


O01 task name in use 

02 file not found 

03 specified partition too small 

04 task and partition base mismatch 

07 length mismatch common block 

08 base mismatch common block 

09 too many common block requests 

11 checkpoint area too small 

13 not enough APRs for task image 

14 file not a task image 

15 base address must be on 4K boundary 

16 illegal first APR 

18 common block parameter mismatch 

20 common block not loaded 

22 task image virtual address overlaps common block 
23 task image already installed 

24 address extensions not supported 

26 checkpoint space too small, using checkpoint file 
24 no checkpoint space, assuming not checkpointable 
29 illegal UIC 

30 no pool space 

31 illegal use of partition or region 

32 access to common block denied 

33 task image I/O error 

34 too many LUNs 

35 illegal device 

36 task may not be run 

37 task active 

39 task fixed | 

40 task being fixed 

4] partition busy 

43 common/task not in system 

44 region or common fixed 

45 cannot do receive 

47 invalid request 

48 cannot return status 

49 error encountered on file open operation 


E=Z 


APPLICATION CANNOT BE STARTED 


50 error encountered on file close operation 
51 cannot get file LBN to process label blocks 
99 too many tasks installed (limit is 20) 

—4 n Reserved for internal PRO/Dispatcher use 

-5 n Reserved for internal PRO/Dispatcher use. 

-6 n Error occurred during Main Menu display. 

-7 n Error occurred while loading PRO/Communications 


software driver. 


-8 n Error occurred while loading OPTIONS Graphics software. 


E.2 SYSTEM ABORTED TASK 


Elements of Status Array 


0 odd address and other traps to 4 

2 memory protect violation 

4 break point instruction (BPT) or trace trap (T-bit) 
6 IOT instruction 


8 l1llegal or reserved instruction 

10 non-RSX EMT instruction 

12 TRAP instruction 

14 11/40 floating point exception 

L6 SST abort - bad stack 

18 AST abort - bad stack 

20 abort via directive (ABRTS) 

22 task load read failure 

24 task checkpoint read failure 

26 task exit with outstanding I/O 

28 task memory parity error 

30 task aborted with PMD request 

32 ti: virtual terminal was eliminated 

34 task installed in 2 different systems 

36 task aborted due to bad affinity (required 
bus runs are offline or not present) 

38 task has run over its time limit 


E.3 BUGCHECK CODES 


000100 
XXXXXX 


000200 
XXXXXX 


100400 
XXXXXX 


000300 
000000 


000300 
000001 


000300 
000002 


000300 
000003 


000300 
000004 


000300 
000005 


000300 
000006 


000300 
000007 


000300 
000010 


000300 
XXXXXX 


000400 
000001 


000400 
000002 


000400 
000003 


BUGCHECK CODES 


P/OS Keyboard Handler error 


Terminal Driver error 


P/OS Terminal Subsystem error 


P/OS Executive 


or other system 


IOT in System State 


P/OS Executive 
Stack Overflow 


P/OS Executive 


or other system 


or other system 


Trace Trap or Breakpoint 


P/OS Executive 


or other system 


Illegal Instruction Trap 


P/OS Executive 
Odd Address or 


P/OS Executive 
Segment Fault 


P/OS Executive 
A Task on P/OS 


P/OS Executive 
EMT Trap 


P/OS Executive 
TRAP Trap 


or other system 
Other Trap 4 


or other system 


or other system 


Without a Parent Aborted 


or other system 


error 


error 


error 


error 


error 


error 


error 


error 


or other system error 


P/OS Executive or other system error 
Programmed call to Bugcheck macro 


System Startup Processing error 


Can't Install Task CBOOT 


System Startup Processing error 


Can't Spawn Task CBOOT 


System Startup Processing error 


Can’t Spawn Task CMAIN 


000400 
000007 


000400 
000010 


000400 
000011 


000400 
000012 


000400 
000013 


000400 
000014 


000400 
000015 


000400 
000016 


BUGCHECK CODES 
System Startup Processing error 
Required File Not Found 


System Startup Processing error 
DSR corrupt 


System Startup Processing error 
Bad dispatch 


System Startup Processing error 
No way to boot via DECNA 


System Startup Processing error 
DSR allocation failure 


System Startup Processing error 
DDM vector in use 


System Startup Processing error 
Required PDV not found 


System Startup Processing error 
Required hardware not present 


APPENDIX F 


POSRES USER INTERFACE LIBRARY SUMMARY 


Close current help definition file. 
HCLOSE (status) 

Close current menu file. 
MCLOSE (status) 

Display dynamic single-choice menu. 


DMENU (status, action, buflen, strlen, display, add_opt, 
msgl, buflen, msg2, buflen) 


Display help frame. 
HELP (status, frameid, buflen) 
Display multiple-choice menu. 
MMENU (status, opt_buff, opt_len, opt_count, max_opt, 
resp count, resp array, add opt, 
msgl, buflen, msg2, buflen) 


Display static single-choice menu. 


MENU (status, action, buflen, strlen, display, ad_opt, 
msgl, buflen, msg2, buflen) 


Display "Application error..." message, followed by specified message. 


FATLER (message, buflen) 


POSRES Summary 


Get single keystroke without echo. 
GETKEY (status) 
Display P/OS New File Specification form. 


NEWFIL (status, filespec, buflen, strlen, deftype, buflen, 
| strlen, text, buflen, msg, buflen) 


Display P/OS File Selection Menu. 
OLDFIL (status, maxfiles, files, strlens, 
wildcard, buflen, textl, buflen, 
msgl, buflen, msg2, buflen) 
Open help definition file and set default help frame. 
HFILE (status, filespec, buflen, frameid, buflen) 
Open menu definition file. 
MFILE (status, filespec, buflen) 
Pack (store information in) dynamic menu buffer. 
DPACK (status, group,...) 


The format of a group is: 


buflen, fieldval, buflen 


Pack (store information in) multiple-choice menu buffer. 
MPACK (status, group,...) 


The format of a group is: 


POSRES Summary 


Parse string for CSI sequence. 
PRSCSI (status, buff, buflen, csipos) 
Read menu frame into static buffer. 


MFRAME (status, frameid, buflen, 
action, buflen, strlen) 


Read message from file into buffer. 


RDMSG (status, filespec, buflen, frameid, buflen, 
message, buflen, strlen) 


Send message to P/OS Message/Status Display. 
MSGBRD (status, message, buflen) 

Set default help frame. 
HFRAME (status, frameid, buflen) 

Unpack (return information stored in) static buffer. 
MUNPK (status, group,...) 


The format of a group is: 


Wait for RESUME key. 


WIRES () 


INDEX 


-A=- 


Action form, 5-9 

help menu, 5-21 

Single-choice menu, 5-18 
Action string 

global, 8-30 

option, 8-4, 8-9, 8-30 
ADB 

see Application Diskette 

Builder 


Additional Options flag, 8-4, 8-7, 


8-9 
ALUNS directive 
Communications, 2-2 
APPLSDIR, 6-3 to 6-4, 8-17, 8-19, 
8-27 
APPLSDST, 6-5 
Application 
multiple diskette, 1-5 
Application directory, 1-1, 1-4, 
8-17, 8-19, 8-27 
and Fast Install, 3-1 


Application Diskette Builder, 1-l, 


1-5, 6-8 
and Fast Install, 3-2 
and installation command file, 
l=] to l=2 
bad block checking, 1-3 
checkpoint file, 1-3 
Application installation file 
see Installation 


-B- 


Background task, 6-7 
Bad block 

checking by ADB, 1-3 
BASIC-PLUS-2, 6-10, 6-12 
Bugcheck codes, E-4 


-C- 


CET 

see PROSE 
Checkpoint file, 1-3, A-3 
COBOL~81, 6-10, 6-12 


Index-l 


CODEC input on TMS line, 2-39 
Collating sequence 


PRO/SORT, 11-5 


Communications 


Base System Services, 2-1 

CCANS routine, 2-14, 2-40 

CCATA routine, 2-2, 2-8 to 2-9, 
2-40, 2-42 

CCATT routine, 2-8 to 2-9 

CCAUXK routine, 2-40 

CCBRK routine, 2-19 

CCDET routine, 2-9 

CCDIAL routine, 2-13 

CCDTMF routine, 2-42 

CCFLSH routine, 2-19 

CCGMC routine, 2-6, 2-10 

CCHNG routine, 2-16, 2-42 

CCKILL routine, 2-20 

CCLCRG routine, 2-6 to 2-7, 
2-11 

CCLCRP routine, 2-6 to 2-7, 
2-11 

CCMODE routine, 2-40 

CCMTT routine, 2-7, 2-12 

CCORG routine, 2-15, 2-40 

CCPTGV routine, 2-41 

CCRXD routine, 2-18 

CCSMC routine, 2-6, 2-9 

CCSPWN routine, 2-22 

CCTXD routine, 2-17 

COMLIB, 2-1 to 2-3, 2-7, 6-12 

CPHREC routine, 2-23 

CPHSEL routine, 2-24 

device names, 2-2 

FTATT routine, 2-30, 2-34 

FTDET routine, 2-27, 2-31, 2-34, 
2-37 

FTLISN routine, 2-38 

FTNTFY routine, 2-33 to 2-34 

FTOPRN routine, 2-31, 2-34 

FTOPTG routine, 2-28 

FTOPTP routine, 2-28 

FTSERV routine, 2-37 

FTSYNC routine, 2-27, 2-34 to 
2-35 

FTUNPK routine, 2-28, 2-34 to 
2-35 


Communications (Cont.) 
getting line characteristics, 
2-10 
line characteristics, 2-5 
line descriptor block, 2-5 
modem support, 2-6 
service categories, 2 
Status value, 2-2, 2- 
translate table, 2-6 
XKDRV, 2-1, 2-7 to 2 
CORE Graphics Library, 
CSI sequence 
parsing, 8-25 


-D=— 


DIBOL, 6-10 
Diskette 
labelling, 1-5 
DISKETTE.INS, 1-4 
Display form, 5-5, 5-9, 5-12 
help menu, 5-20 
help text frame, 5-23 
message frame, 5-24 
Dynamic menu 
displaying, 8-4 


-E- 


Escape sequence 
PROSE, 10-3 

Event flag 
Communications, 2-2 


-F— 


Fast Install, 3-1 to 3-2 
and Application Diskette 
Builder, 3-2 
and P/OS Diskette, 3-1 
Fatal error 
handling, 8-11 
FCS 
see File Control Services 
FDT 
see Frame Development Tool 
File Control Services, 4-1, 4-3 
and logical names, 4-2 
and Micro/RSX, 4-3 
and named directories, 4-2 
and numeric directories, 4-2 


INDEX 


File Control Services (Cont.) 
and P/OS current directory, 4-2 
and version numbers, 4-2 
Support for various languages, 
4-3 
File name 
input routine, 8-13 
selection routine, 8-15 
File Selection Menu, 8-15 
File specification 
default, 8-19 
P/OS default, 8-17 
use of, 8-13, 8-15 
FORTRAN-77, 6-10, 6-12 
Frame 
computing buffer size, 5-5 
Frame Development Tool, 5-1, 5-26 
ACTION command, 5-1, 5-9 to 
5-10, 5-12, 5-26 
ADD command, 5-1, 5-3, 5-12, 
5-25 
and POSRES, 5-1 
CONVERT command, 5-4 
DELETE command, 5-1, 5-5 
DISPLAY command, 5-9, 5-12, 
5-25 
DISPLAY commmand 
error messages, 
Errors, 5-24 
EXIT command, 5 
FILE command, 5 
file types, 5-6 
5 
5 


WW ~ 
| 


HELP command, 

LIST command, 

MODIFY command, 
5-26 

NAME command, 5-1, 5- 

on RSX-11M/M-PLUS, 5- 

on VAX/VMS, 5-2 

PROFILE command, 5-1, 5-11 to 
5-12, 5-26 

QUIT command, 5-1, 5-3, 5-7 to 
5-8, 5-ll, 5-26 

REPORT command, 5-1, 5-8 

SAVE command, 5-1l, 5-8, 5-ll, 
5-26 

use of keypad, 5-14 

Function key 
codes, D-l 


Lg DH Og SLO 
15. S=6 
a= b= 1g: DOLL, 


5 
2 


Index-2 


-G- 


GBLDEF option 
Communications, 2-30 


2h= 


Help file 
closing, 8-3 
opening, 8-17 
Help frame 
default, 8-17 
specifying, 8-29 
displaying, 8-6 


-~jT=— 


I/O status block 
Communications, 2-2 
Input 
Single keystroke, 8-12 
Installation 
and Application Diskette 
Builder, 6-1 
and P/OS Diskette, 6-1 
and PRO/Dispatcher, 6-1 


ASSIGN HELP command, 6-3, A-4 
ASSIGN LOGICAL command, 6-3 

ASSIGN MENU command, 6-4, A-4 
command file, 1-2, 6-1, 6-12 


tf 
and Fast Install, 3-l 
errors, A-l 
format, 6-2 
PRO/SORT, 11-2 
PROSE, 10-2 
used by ADB, 1-1 
comment delimiter, 6-4 
CORE Graphics Library, 6-9 
EXECUTE command, 6-4 
FILE command, 1-4, 6-2, 6-4 to 
6-5, 6-8, A-2 
INSTALL command, 6-2, 6-6, A-2 
to A-3 
options, 6-2 
LOAD command, 3- 
MOUNT command, l 
6-8, A-6 
NAME command, 6-8 
optimization, 6-2 
OPTIONS command, 3-l 
order of commands, 6 


, A-l, A-5 


INDEX 


Installation (Cont.) 
P/OS Disk/Diskette Services, 
6-1 
PRO/GIDIS, 6-9 
REQUIRE command, 3-1, 6-7, 6-9 
RUN command, 6-9, A-1l to A-2, 
A-4 


-—-K=— 


Keypad 

use Of with FDT, 5-1 
Keystroke 

input routine, 8-12 


-L— 


Line descriptor block 
Communications, 2-5 

Logical name 
and FCS, 4-2 
in Installation Command File, 

6-3 

Logical unit number 

Communications, 2-l 


-M— 


MACRO-11, 7-1 
and FCS, 4-3 
and PRO/SORT, 11-2 
Menu file 
closing; 8=3 
opening, 6=19 
reading from, 8-26 
Message 
sending, 8-28 
Message file 
reading from, 8-27 
Message/Status Display, 8-28, C-2 
LO: iCx3 
Micro/RSX 
and FCS, 4-3 
Modem 
Support for, 2-6 
Multiple diskette application 
P/OS Hard Disk, 1-4 
Multiple-choice menu 
displaying, 8-7 
packing, 8-23 


Index-3 


INDEX 


-N=- 
New File Specification form, 8-13 
-—Pp— 


P/OS 
error codes, E-1l 
P/OS Diskette 
and NEWFIL, 8-14 
and OLDFIL, 8-16 
PASCAL, 6-10, 6-12 
Plotter, 6-12 
PMA 
see Professional Macro 
Assembler 
POSRES, 8-1, 8-32 
and FDT, 5-1 
and registers, 8-1 
DMENU routine, 8-4, F 
DPACK routine, 8-20, 
FATLER routine, 8-1ll 
GETKEY routine, 8-12 
C-2, F-2 
HCLOSE routine, 8 
HELP routine, 8-6, 
HFILE routine, 6-3, 
HFRAME routine, 8-29, 
MCLOSE routine, 8-3 
MENU routine, 8-9 
MFILE routine, 6-4, 
MFRAME routine, 8-26 
MMENU routine, 8 
MPACK routine, 8- 
MSGBRD routine, 8-28, F-3 
MUNPK routine, 8-30, F-3 
NEWFIL routine, 6-12, 8-13, F-2 
P/OS Diskette, 8-14 
OLDFIL routine, 6-12, 8-15, C-3, 
F-2 
P/OS Diskette, 8-16 
omitting parameters, 8-2 
parameter checking, 8-2 
parameter format, 8-2 
parameter types, 8-l 
PRSCSI routine, 8-25, C-2, F-3 
RDMSG routine, 8-27, F-3 
status block, 8-1 
status codes, C-l 
valid frame identifiers, 5-3 
WTRES routine, 8-32, F-3 


Print Services, 6-12, 9-1, 9-3 
condition codes, 9-2 
CPRINT routine, 9-1 
error codes, 9-2 
P/OS Diskette, 9-3 
P/OS Hard Disk, 9-3 
PRO/Communications Services, 2-1 
PRO/Dispatcher 
and Installation Command File, 
6-] 
PRO/FMS-11, 6-12 
PRO/GIDIS, 6-9, 6-12 
PRO/RMS-11, 4-1 
and Fast Install, 3-2 
PRO/SORT, 6-12, 11-1, 11-20 
calling, 11-1 
COLLATE command, 11-3 to 11-5, 
11-10 
command file 
nesting, 11-4 
specifying, 1ll-l 
comment, 11-3 
data types, 11-7 
DEFAULT command, 11-3 to 11-5 
error codes, 11-15 
event flag number, 11-2 
example, 11-17 
FIELD command, 11-3, 11-6, 11-9 
FILE command, 11-2 
FORCE command, 11-3, 11-9 
INCLUDE command, 11-3, 1l1l-ll 
INPUT command, 11-3, 11-12 
maximum record lengths, 11-2 
OUTPUT command, 11-3, 11-12 
PROCESS command, 11-2 to 11-3, 
l1l-12 to 11-13 
pseudo-fields, 11-9 
record formats, 11-2 
SORT command, 11-3, 11-13 
WRITE command, 11-2 to 11-3, 
11-9, 11-14 
PRODIR (POSSUM), 6-12 
PROFBI (POSSUM), 6-12 
Professional Application Builder, 
6-10, 8-1 
Communications, 2-3 
Professional Macro Assembler, 7-1 
to 7-2, 8-1 
PRO/Tool Kit, 7-1 
RSX-11M/M-PLUS, 7-1 
VAX/VMS, 7-1 


Index-4 


INDEX 


Profile form, 5-4, 5-1ll to 5-12 SORT-11 
help menu, 5-19 ALTSEOQ command, 11-5 
help text frame, 5-22 SYSLLB, 6—26 
message frame, 5-24 
single-choice menu, 5-16 -T- 
PROSE, 10-1, 10-5 
Callable Editor Task, 6-10, Task name, A-3 
6-12, 10=1 TASK option, 6-10 
event flag number, 10-1 Telephone Management System, 2-1, 
margin settings, 10-3 2-7, 6-12 
status codes, 10-3 Terminal 
PROTSK routine (POSSUM), 6-7 detaching, 10-2 
TMS 
-R- see Telephone Management System 
Translate table 
REMOVE command (DCL), 6-7 format, 2-6 
RESUME key 
programming, 8-32 -W- 
=S- Wild card 


use of, 8-15 to 8-16 
Single-choice menu | 
displaying, 8-9 


dynamic -Z- 
packing, 8-20 

static ZZAPPL, 1-4 
unpacking, 8-30 ZZAPPL.INS, 1-4 
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